Add agent packet mode

[lzehrung]

Summary

• add orientation and packet retrieval APIs with stable file and review handles
• add orient and packet get CLI commands plus MCP orient and packet_get tools
• document the first-turn orientation workflow in README, CLI/API docs, agent workflows, and bundled skill guidance

Verification

• PASS: npm run lint
• PASS: npm run build
• PASS: npx vitest run tests/agent-orient.test.ts tests/agent-packet.test.ts tests/mcp-server.test.ts tests/cli-command-modules.test.ts tests/cli-regressions.test.ts tests/package-metadata.test.ts
• PASS: git diff --check main...HEAD
• FAIL: npm run test:ci, due existing Windows native/fallback failures seen before this branch: invalid codegraph-js-fallback Tree-sitter binding, graph-only syntax-tree reconstruction tests, and native-vs-JS parity expectations

[kilo-code-bot]

Code Review Summary

Status: No New Issues Found | Recommendation: Merge

Resolved Issues

The following previously reported issues were addressed in commits since the last review:

File	Line	Issue	Status
src/agent/packet.ts	42	getCodegraphPacket() always creates an agent session	Resolved by early review check before session creation
src/agent/packet.ts	141	decodeURIComponent() can throw on malformed percent-encoding	Resolved by decodeReviewHandleField with try/catch
src/cli/orient.ts	N/A	ORIENT_HELP_TEXT imported but never used	Resolved by removing unused import

Previous Issues Still Active

The following previously reported inline comments remain active on unchanged code:

• src/mcp/tools.ts (lines 56, 67)
• src/mcp/server.ts (lines 104, 109, 651, 657)
• src/agent/orient.ts (line 249, and 2 N/A observations)
• src/cli.ts (line 253)
• src/cli/help.ts (N/A)
• docs/cli.md (N/A)
• codegraph-skill/codegraph/SKILL.md (N/A)
• docs/agent-workflows.md (N/A)

Files Reviewed (2 files)

• src/agent/packet.ts — refactoring to avoid unnecessary session setup for review packets, no issues
• src/cli/orient.ts — removed unused import, no issues

---

_{Reviewed by kimi-k2.6 · 435,029 tokens}

[Copilot]

Pull request overview

Adds an “agent packet mode” workflow to Codegraph: a compact first-turn repo orientation response that returns stable handles, plus a packet retrieval API/CLI/MCP tool to fetch bounded evidence by handle (including review-range packets).

Changes:

• Introduces orientCodegraph() / getCodegraphPacket() APIs and corresponding CLI commands (codegraph orient, codegraph packet get).
• Extends MCP with orient and packet_get tools and handler wiring.
• Adds tests and documentation describing the first-turn orientation → packet follow-up workflow.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
tests/mcp-server.test.ts	Validates MCP tool registration and orient/packet handler behavior
tests/cli-regressions.test.ts	Adds CLI regression tests for orient output and packet get behavior
tests/cli-command-modules.test.ts	Ensures --help routing covers orient/packet commands
tests/agent-orient.test.ts	New tests for orientation API response shape/handles
tests/agent-packet.test.ts	New tests for packet retrieval (file + review)
src/mcp/tools.ts	Adds MCP tool schemas for orient and packet_get
src/mcp/server.ts	Adds MCP handler methods + Zod schemas for orient/packet_get
src/index.ts	Exports new agent orientation/packet APIs and types
src/cli/orient.ts	Implements codegraph orient command and pretty formatting
src/cli/packet.ts	Implements codegraph packet get command and JSON/pretty output
src/cli/options.ts	Registers --budget as a value option
src/cli/help.ts	Adds orient/packet help text and top-level CLI help entries
src/cli.ts	Wires new commands into CLI dispatch and include-roots handling
src/agent/orient.ts	Implements orientation response (tree/modules/health/handles)
src/agent/packet.ts	Implements packet retrieval wrapper around explain/review packets
README.md	Documents the orient → packet-get first-turn workflow
docs/library-api.md	Documents new library APIs and MCP handler usage
docs/cli.md	Documents new CLI commands and updates command overview
docs/agent-workflows.md	Adds orientation packet workflow guidance
codegraph-skill/codegraph/SKILL.md	Updates skill guidance to recommend orient/packet workflow

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.