@gokulvenkatareddy/cortex 0.1.7

package/apps/octogent/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  quality:
+    name: Lint, Test, Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.4.1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Test
+        run: pnpm test
+
+      - name: Build
+        run: pnpm build

package/apps/octogent/.shims/claude

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Octogent expects `claude` as the agent CLI. We route it to CORTEX.
+# CORTEX_REPO_ROOT is set by bin/cortex-octogent before launch.
+exec node "${CORTEX_REPO_ROOT:-/Users/gokul/Documents/openclaude}/cortex.mjs" "$@"

package/apps/octogent/AGENTS.md

@@ -0,0 +1,71 @@
+# Repository Guidelines
+
+## Code Style First
+- Preserve existing patterns before inventing new ones. Read nearby code and match the established module shape, naming, and data flow unless there is a clear reason to change direction.
+- Start with tests. For bug fixes, reproduce first. For new features, add the test that defines the behavior before expanding the implementation.
+- Implement incrementally. Prefer small, working steps over broad rewrites. Keep the tree passing as you go.
+- Think in systems. Extract shared behavior into reusable components, hooks, utilities, or domain functions instead of cloning slightly different versions.
+- Keep modules focused. Large React containers should orchestrate, not hold every constant, parser, and JSX block. Keep pure logic in `src/app/*`, UI in `src/components/*`, and CSS split into focused files under `src/styles/*`.
+- Comments explain why, not what. Add comments only for constraints, tradeoffs, or non-obvious reasoning.
+- Design defensively. Validate assumptions, handle edge cases, and treat security boundaries as part of the implementation, not a follow-up.
+
+## Project Structure
+- Monorepo: `apps/*` and `packages/*` via `pnpm-workspace.yaml`.
+- Runtime: Node.js 22+, TypeScript, `pnpm`.
+- Core package: `packages/core`
+  - Framework-agnostic domain types, application logic, and ports.
+  - Must stay free of React, HTTP, PTY, and filesystem orchestration concerns.
+- API app: `apps/api`
+  - Node HTTP/WebSocket server, PTY session runtime, worktree lifecycle, transcript persistence, monitor service.
+- Web app: `apps/web`
+  - Vite + React operator UI, modular CSS, UI orchestration over API/runtime contracts.
+- Runtime state: `.octogent/`
+  - `state/tentacles.json`
+  - `state/transcripts/*.jsonl`
+  - `worktrees/<tentacleId>`
+
+## Documentation Map
+- Start at `README.md` for the product overview and command surface.
+- Docs index: `docs/index.md`
+- Core concepts:
+  - `docs/concepts/mental-model.md`
+  - `docs/concepts/tentacles.md`
+  - `docs/concepts/runtime-and-api.md`
+- Workflow guides:
+  - `docs/guides/working-with-todos.md`
+  - `docs/guides/orchestrating-child-agents.md`
+  - `docs/guides/inter-agent-messaging.md`
+- References:
+  - `docs/reference/cli.md`
+  - `docs/reference/api.md`
+  - `docs/reference/filesystem-layout.md`
+  - `docs/reference/troubleshooting.md`
+- Read only the docs relevant to the surface you are touching. Do not do a full docs sweep unless the task is documentation maintenance.
+
+## Architecture Boundaries
+- `packages/core` defines domain contracts and pure application logic. Both apps may depend on it; it must not depend on app code.
+- `apps/api` owns infrastructure concerns: PTYs, WebSockets, filesystem persistence, process execution, and git worktree operations.
+- `apps/web` owns presentation and client-side interaction state. Do not move server-only behavior into the web app to avoid adding hidden backend logic to the UI.
+- If behavior is reusable across apps, move it into `packages/core` only when it can remain framework-agnostic.
+- Keep orchestration thin. Entry points such as API server/bootstrap files and top-level React containers should wire dependencies, not accumulate business logic.
+
+## Workflow
+- Read only the guides and code relevant to the surface you are changing. Do not sweep the whole repo before starting.
+- Prefer small, isolated edits over broad cleanup unless the task explicitly asks for refactoring.
+- Keep docs in sync with behavior changes when user-facing workflows, commands, persistence layout, or architecture assumptions change.
+- Preserve the product vocabulary already documented in `CLAUDE.md`: agents, sessions, worktrees, logs, pipelines, tentacles, and terminal columns.
+
+## Verification
+- Install: `pnpm install`
+- Dev: `pnpm dev`
+- Build: `pnpm build`
+- Test: `pnpm test`
+- Lint: `pnpm lint`
+- Format: `pnpm format`
+- For narrow changes, run the most direct test or package-scoped test first, then widen verification as needed.
+- For changes that affect shared contracts, persistence, or cross-app behavior, run the relevant package tests and the root build before landing.
+
+## Scoped Guides
+- `apps/api/AGENTS.md` expands server/runtime/worktree rules.
+- `apps/web/AGENTS.md` expands UI/component/style rules.
+- `packages/core/AGENTS.md` expands domain and ports-and-adapters rules.

package/apps/octogent/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing
+
+Octogent is an experimental personal project. Contributions are welcome, but the bar is accuracy over volume. Keep changes small, test-backed, and easy to review.
+
+## Before you change anything
+
+- read the relevant docs in `docs/`
+- check whether the behavior already exists in the API or UI before adding more surface area
+- keep the project Claude Code-first in docs and product framing
+- do not document speculative features as if they already work
+
+## Prerequisites
+
+- Node.js `22+`
+- pnpm
+- `claude` for the supported agent workflow
+- `git` for worktree features
+
+## Setup
+
+```bash
+pnpm install
+```
+
+## Development
+
+```bash
+pnpm dev
+```
+
+The dev runner starts the local API and web app together.
+
+## Required checks
+
+Run these before opening a pull request:
+
+```bash
+pnpm test
+pnpm lint
+pnpm build
+```
+
+Use `pnpm format` if you need to rewrite formatting.
+
+## What good contributions look like
+
+- incremental changes with clear scope
+- tests for behavior changes
+- docs updated in the same change when workflows or concepts change
+- code and docs that reflect the current implementation, not a roadmap
+
+## Docs policy
+
+- `docs/` is for contributor and future-agent understanding
+- if you change tentacles, todos, terminals, orchestration, or messaging, update the matching docs page
+
+## Pull request expectations
+
+- explain the problem in one short paragraph
+- explain the behavior change in concrete terms
+- mention any persistence, API, or workflow impact
+- include screenshots for visible UI changes
+- call out missing follow-up work explicitly instead of hiding it
+
+## Areas that matter most right now
+
+- tentacle model and agent-facing context files
+- todo parsing and delegation flow
+- Claude Code terminal lifecycle
+- child-agent orchestration
+- inter-agent messaging
+- fixing existing issues and optimize for reliability

package/apps/octogent/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/apps/octogent/README.md

@@ -0,0 +1,184 @@
+<div align="center">
+
+<img width="1500" height="500" alt="Octogent header" src="./static/images/octogent-header.png" />
+<br/>
+<br/>
+
+<strong>too many terminals, not enough tentacles</strong>
+<br />
+<br />
+
+![Last Update](https://img.shields.io/github/last-commit/hesamsheikh/octogent?label=Last%20Update&style=flat-square)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-22+-5FA04E?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Follow on X](https://img.shields.io/badge/Follow%20on-X-000000?style=flat-square&logo=x)](https://x.com/Hesamation)
+[![Discord](https://img.shields.io/badge/Discord-Open%20Source%20AI%20Builders-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/vtJykN3t)
+
+</div>
+
+# Octogent
+
+It's really not fun to have **ten Claude Code sessions open at once**, constantly switching between them and trying to remember what each one was supposed to do. *Things get blurry fast* when one agent is doing documentation, another is touching the database, another is changing the API, and another is somewhere in the frontend. **Octogent** tries to fix that by giving each job its own <u>scoped context, notes, and task list</u>, while also making it possible for Claude Code to **spawn other Claude Code agents**, assign them work, and communicate with them.
+
+## The Vision
+
+This repo is a personal exploration of what an AI coding environment might look like when terminal coding agents are treated as parts of a bigger orchestration layer, not the final interface by themselves. The point is not to hide **Claude Code** behind abstractions. The point is to make *multi-agent work less chaotic for the developer* on a real codebase.
+
+## Screenshots
+
+<div align="center">
+<table>
+<tr>
+<td><img src="./static/images/preview_1.jpg" alt="Screenshot 1" width="100%"/></td>
+<td><img src="./static/images/preview_2.jpg" alt="Screenshot 2" width="100%"/></td>
+</tr>
+<tr>
+<td><img src="./static/images/preview_3.jpg" alt="Screenshot 3" width="100%"/></td>
+<td><img src="./static/images/preview_4.jpg" alt="Screenshot 4" width="100%"/></td>
+</tr>
+<tr>
+<td><img src="./static/images/preview_5.jpg" alt="Screenshot 5" width="100%"/></td>
+<td><img src="./static/images/preview_6.jpg" alt="Screenshot 6" width="100%"/></td>
+</tr>
+</table>
+</div>
+
+## What Octogent Does for You
+
+- **Creates tentacles as context layers** so agents can work with scoped markdown files instead of broad, messy chat context
+- **Uses `todo.md` as an execution surface** so tasks stay visible, trackable, and ready for delegation
+- **Runs multiple Claude Code terminals** so one developer can coordinate several coding sessions at once
+- **Spawns child agents from todo items** so parallel work has a concrete source of truth
+- **Supports inter-agent messaging** so workers and coordinators can report completion, blockers, and handoff notes
+- **Keeps agent-facing context in files** so the system is more durable than a single prompt thread
+- **Provides a local API and UI** for terminal lifecycle, persistence, websocket transport, and orchestration
+
+A **tentacle** is a folder under `.octogent/tentacles/<tentacle-id>/` that holds agent-readable markdown such as `CONTEXT.md`, `todo.md`, and any extra notes needed for that slice of the codebase.
+
+The octopus metaphor is literal: *one octopus, many tentacles, different work happening at the same time*.
+
+## Tentacles
+
+A **tentacle** is a scoped job container. It gives one slice of work its own files, notes, and `todo.md` so the agent is not forced to reconstruct the entire codebase context from chat history.
+
+What it does:
+
+- keeps context local to one area such as documentation, database work, API changes, or frontend work
+- gives agents durable files they can read and update
+- provides a natural source for delegation through todo items
+
+For the full model, see [Tentacles](docs/concepts/tentacles.md) and [Working With Todos](docs/guides/working-with-todos.md).
+
+## Context, Notes, and Task Lists
+
+In Octogent, a tentacle is not only a task bucket. It is also where the job keeps its local context. That can include notes about one part of the codebase, implementation details, handoff files, and a `todo.md` that tracks what still needs to happen. A Claude Code agent can read and update those files as the work moves forward.
+
+That means you can:
+
+- keep documentation, database, API, or frontend work separated into different job contexts
+- store the notes that help an agent understand that part of the codebase
+- spawn one agent for one specific item
+- break a larger job into multiple items
+- launch a swarm so several agents work through the list in parallel
+- use the files inside the tentacle as the shared source of truth for what is done and what is left
+
+For the full model, see [Tentacles](docs/concepts/tentacles.md) and [Working With Todos](docs/guides/working-with-todos.md).
+
+## Claude Code Managing Claude Code
+
+One of the main ideas here is that **Claude Code** should not only be treated as a single terminal session waiting for a human prompt. In Octogent, one Claude Code agent can coordinate other Claude Code agents, assign them specific jobs, and exchange short messages with them while the human stays at the orchestration layer.
+
+This is different from Claude Code's subagent spawning, since it allows you to directly see and control what each worker agent is doing.
+
+That means Octogent is not just a dashboard for multiple terminals. It is also a way to structure parent-worker behavior around scoped tasks and shared context files.
+
+For the current model, see [Orchestrating Child Agents](docs/guides/orchestrating-child-agents.md) and [Inter-Agent Messaging](docs/guides/inter-agent-messaging.md).
+
+## How It Works
+
+1. Create a tentacle for a scoped slice of work.
+2. Store context, notes, and `todo.md` inside that tentacle so the agent has durable, local guidance.
+3. Run one or more agent terminals against that tentacle, and delegate child work from the task list when needed.
+4. Use the local API and web UI to monitor sessions, messages, transcripts, and worktree state.
+
+## Quick start
+
+<details>
+<summary><strong>Local development</strong></summary>
+
+```bash
+pnpm install
+pnpm dev
+```
+
+This starts the API and web app for local development.
+
+</details>
+
+<details open>
+<summary><strong>Current install status</strong></summary>
+
+```bash
+Octogent is not published to the npm registry yet.
+```
+
+For local development:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+For a local global CLI install from a clone:
+
+```bash
+pnpm install
+pnpm build
+npm install -g .
+octogent
+```
+
+The registry install flow `npm install -g octogent` will only work after the package is published.
+
+</details>
+
+On first run, **Octogent** creates the local `.octogent/` scaffold automatically, assigns a stable project ID, picks an available local API port starting at `8787`, and opens the UI unless `OCTOGENT_NO_OPEN=1` is set.
+
+## Requirements
+
+- Node.js `22+`
+- `claude` installed for the supported agent workflow
+- `git` for worktree terminals
+- `gh` for GitHub pull request features
+- `curl` for the current Claude hook callback flow
+
+Startup fails if neither `claude` nor another supported provider binary is installed. The current docs only cover **Claude Code**.
+
+## What persists
+
+- `.octogent/` keeps project-local scaffold and worktrees
+- `~/.octogent/projects/<project-id>/state/` keeps runtime state, transcripts, monitor cache, and metadata
+- `.octogent/tentacles/<tentacle-id>/` keeps the context files and todos that agents read
+
+PTY sessions survive browser reloads during the idle grace period, but they do **not** survive an API restart.
+
+## Docs
+
+- [Docs Home](docs/index.md)
+- [Installation](docs/getting-started/installation.md)
+- [Quickstart](docs/getting-started/quickstart.md)
+- [Mental Model](docs/concepts/mental-model.md)
+- [Tentacles](docs/concepts/tentacles.md)
+- [Runtime and API](docs/concepts/runtime-and-api.md)
+- [Working With Todos](docs/guides/working-with-todos.md)
+- [Orchestrating Child Agents](docs/guides/orchestrating-child-agents.md)
+- [Inter-Agent Messaging](docs/guides/inter-agent-messaging.md)
+- [CLI Reference](docs/reference/cli.md)
+- [Filesystem Layout](docs/reference/filesystem-layout.md)
+- [API Reference](docs/reference/api.md)
+- [Experimental Features](docs/reference/experimental-features.md)
+- [Troubleshooting](docs/reference/troubleshooting.md)
+- [Contributing](CONTRIBUTING.md)
+
+## Contributor setup
+Contributions are welcome 🤗. For contributor workflow and expectations, see [CONTRIBUTING.md](CONTRIBUTING.md).

package/apps/octogent/apps/api/AGENTS.md

@@ -0,0 +1,32 @@
+# API Guidelines
+
+## Ownership
+- `apps/api` owns HTTP/WebSocket routing, PTY session orchestration, worktree lifecycle, transcript persistence, monitor service, and runtime integrations.
+- Keep infrastructure details here. Do not push PTY, filesystem, process, or git orchestration into `packages/core` or `apps/web`.
+
+## Relevant Docs
+- `docs/concepts/runtime-and-api.md`
+- `docs/reference/api.md`
+- `docs/reference/filesystem-layout.md`
+- `docs/reference/troubleshooting.md`
+- Read these when changing API contracts, runtime lifecycle behavior, persistence layout, or operator-facing server workflows.
+
+## Boundaries
+- Treat `packages/core` as the source of framework-agnostic types and application logic.
+- API routes and request parsers may adapt input into core/application shapes, but avoid embedding large business rules directly in route handlers.
+- Keep request parsing, route wiring, runtime orchestration, and persistence concerns in separate modules when the file structure already supports it.
+- Do not make the web app depend on server-only implementation details. Expose stable API/runtime contracts instead.
+
+## State And Persistence
+- Runtime state under `.octogent/` is a contract surface. Be careful with compatibility when changing file formats or paths.
+- Transcript, tentacle registry, monitor config, and worktree data should remain predictable and inspectable on disk.
+- Prefer explicit migration or normalization paths over silent shape drift.
+
+## PTY, Process, And Git Safety
+- Treat PTY/session lifecycle code as stateful and failure-prone. Handle cleanup, disconnects, and partial failures explicitly.
+- For worktree operations, prioritize correctness and recoverability over clever automation.
+- Avoid destructive filesystem or git behavior unless the task explicitly requires it and the UI/API surface makes the action clear.
+
+## Testing
+- Add targeted tests for request parsing, route behavior, persistence compatibility, and runtime edge cases when touching those surfaces.
+- For bug fixes, reproduce with a test before changing runtime logic when feasible.

package/apps/octogent/apps/api/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@octogent/api",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "build": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@octogent/core": "workspace:*",
+    "node-pty": "^1.1.0",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.20.6"
+  }
+}

package/apps/octogent/apps/api/src/agentStateDetection.ts

@@ -0,0 +1,181 @@
+import type { AgentRuntimeState } from "@octogent/core";
+
+export type { AgentRuntimeState };
+
+const PROCESSING_PATTERN = /esc to interrupt/i;
+
+const DEFAULT_MAX_BUFFER_LENGTH = 256;
+const DEFAULT_IDLE_AFTER_MS = 1_600;
+
+const ESCAPE_CODE = 27;
+const BEL_CODE = 7;
+const CSI_MARKER = 91;
+const OSC_MARKER = 93;
+const ST_MARKER = 92;
+
+const stripAnsiAndControlSequences = (value: string) => {
+  let cleaned = "";
+
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code !== ESCAPE_CODE) {
+      cleaned += value[index] ?? "";
+      continue;
+    }
+
+    const marker = value.charCodeAt(index + 1);
+    if (marker === CSI_MARKER) {
+      index += 2;
+      while (index < value.length) {
+        const csiCode = value.charCodeAt(index);
+        if (csiCode >= 64 && csiCode <= 126) {
+          break;
+        }
+        index += 1;
+      }
+      continue;
+    }
+
+    if (marker === OSC_MARKER) {
+      index += 2;
+      while (index < value.length) {
+        const oscCode = value.charCodeAt(index);
+        if (oscCode === BEL_CODE) {
+          break;
+        }
+        if (oscCode === ESCAPE_CODE && value.charCodeAt(index + 1) === ST_MARKER) {
+          index += 1;
+          break;
+        }
+        index += 1;
+      }
+      continue;
+    }
+
+    // Consume one-byte escape sequences like ESC c.
+    index += 1;
+  }
+
+  return cleaned;
+};
+
+const normalizeOutput = (chunk: string) => {
+  return stripAnsiAndControlSequences(chunk).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+};
+
+const findLastRelevantMatchIndex = (text: string, pattern: RegExp, chunkStartIndex: number) => {
+  const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
+  const matcher = new RegExp(pattern.source, flags);
+  let latest = -1;
+
+  for (const match of text.matchAll(matcher)) {
+    if (typeof match.index !== "number") {
+      continue;
+    }
+
+    const matchStartIndex = match.index;
+    const matchEndIndex = matchStartIndex + match[0].length;
+    const touchesNewChunk = matchEndIndex > chunkStartIndex;
+    if (!touchesNewChunk) {
+      continue;
+    }
+
+    latest = matchStartIndex;
+  }
+
+  return latest;
+};
+
+const hasProcessingSignal = (text: string, chunkStartIndex: number): boolean =>
+  findLastRelevantMatchIndex(text, PROCESSING_PATTERN, chunkStartIndex) !== -1;
+
+export class AgentStateTracker {
+  private readonly maxBufferLength: number;
+  private readonly idleAfterMs: number;
+  private carry = "";
+  private state: AgentRuntimeState;
+  private idleDeadlineAt: number | null = null;
+
+  constructor({
+    initialState = "idle",
+    maxBufferLength = DEFAULT_MAX_BUFFER_LENGTH,
+    idleAfterMs = DEFAULT_IDLE_AFTER_MS,
+  }: { initialState?: AgentRuntimeState; maxBufferLength?: number; idleAfterMs?: number } = {}) {
+    this.state = initialState;
+    this.maxBufferLength = Math.max(256, Math.floor(maxBufferLength));
+    this.idleAfterMs = Math.max(250, Math.floor(idleAfterMs));
+    if (this.state === "processing") {
+      this.idleDeadlineAt = Date.now() + this.idleAfterMs;
+    }
+  }
+
+  get currentState(): AgentRuntimeState {
+    return this.state;
+  }
+
+  private enterProcessing(now: number): AgentRuntimeState | null {
+    this.idleDeadlineAt = now + this.idleAfterMs;
+    if (this.state === "processing") {
+      return null;
+    }
+
+    this.state = "processing";
+    return "processing";
+  }
+
+  forceState(nextState: AgentRuntimeState, now = Date.now()): boolean {
+    if (nextState === this.state) {
+      if (nextState === "processing") {
+        this.idleDeadlineAt = now + this.idleAfterMs;
+      }
+      return false;
+    }
+
+    this.state = nextState;
+    this.idleDeadlineAt = nextState === "processing" ? now + this.idleAfterMs : null;
+    return true;
+  }
+
+  observeSubmit(now = Date.now()): AgentRuntimeState | null {
+    return this.enterProcessing(now);
+  }
+
+  observeChunk(chunk: string, now = Date.now()): AgentRuntimeState | null {
+    if (!chunk) {
+      return null;
+    }
+
+    const normalized = normalizeOutput(chunk);
+    if (!normalized) {
+      return null;
+    }
+
+    const combined = `${this.carry}${normalized}`;
+    const chunkStartIndex = this.carry.length;
+    this.carry = combined.slice(-this.maxBufferLength);
+
+    if (this.state === "processing" && normalized.trim().length > 0) {
+      this.idleDeadlineAt = now + this.idleAfterMs;
+    }
+
+    if (!hasProcessingSignal(combined, chunkStartIndex)) {
+      return null;
+    }
+
+    return this.enterProcessing(now);
+  }
+
+  poll(now = Date.now()): AgentRuntimeState | null {
+    if (this.state !== "processing" || this.idleDeadlineAt === null) {
+      return null;
+    }
+
+    if (now < this.idleDeadlineAt) {
+      return null;
+    }
+
+    this.state = "idle";
+    this.idleDeadlineAt = null;
+    return "idle";
+  }
+}