Repository navigation
008 agent session linking - #14
Merged
Merged
Conversation
Clarify the 008-agent-session-linking artifacts based on the follow-up finding review. - add structured JSON ambiguity and not-found lookup requirements - distinguish unresolved agent references from direct lookup not-found failures - require cross-platform path validation and documented caveats - require anonymized Claude JSONL contract coverage and export round-trip validation - add repeatable 100+ session performance validation for list and lookup flows - align the plan file map and task dependency graph so US3 depends on US1 and US2
Add recursive discovery for Claude subagent transcripts stored under <main-session>/subagents/, and replace project-wide agent guessing with per-session link resolution that prefers explicit main-session references while retaining nested path ownership as fallback evidence. Expose unresolved referenced child-agent IDs separately from discoverable linked agent IDs, keep main-session list rows scoped to parent sessions, and preserve linked/unresolved agent metadata in CLI views and exports. Extend direct lookup to accept bare and prefixed agent IDs, fail safely on duplicate matches with AmbiguousAgentSessionError, and emit structured JSON lookup failures for ambiguous and missing direct agent IDs. Add nested, conflict, contract, legacy flat-agent, and 100+ session performance coverage, update documentation and quickstart examples, and mark the feature task plan complete. Validation performed: - npm test - npm run typecheck - npm run lint - npm run build - Real-data CLI smoke/regression checks against ~/.claude sessions Per-file summaries: - README.md: Document direct agent lookup, linked/unresolved metadata, and path caveat. - specs/008-agent-session-linking/quickstart.md: Update validation commands and JSON error examples. - specs/008-agent-session-linking/tasks.md: Mark all feature tasks complete. - src/cli/commands/view.ts: Support agent IDs and emit structured ambiguity/not-found JSON errors. - src/cli/formatters/session.ts: Display linked and unresolved agent metadata in session headers. - src/cli/utils/config.ts: Add direct-agent lookup detection and JSON lookup error payload helpers. - src/cli/utils/errors.ts: Refine CLI error handling for agent lookup failure modes. - src/lib/errors.ts: Add AmbiguousAgentSessionError and its type guard. - src/lib/export.ts: Preserve linked and unresolved agent metadata in Markdown exports. - src/lib/index.ts: Re-export ambiguity helpers and updated metadata-bearing types. - src/lib/parser.ts: Extract explicit child-agent references from raw Claude session entries. - src/lib/platform.ts: Add recursive session discovery and nested owner path parsing helpers. - src/lib/session.ts: Implement precise parent-agent linkage, recursive discovery, and ambiguity-safe lookup. - src/lib/types.ts: Add unresolvedAgentIds to SessionSummary and Session. - tests/fixtures/contracts/claude-main-session.jsonl: Add anonymized contract main-session fixture. - tests/fixtures/contracts/claude-main-session/subagents/agent-linked.jsonl: Add anonymized nested agent contract fixture. - tests/fixtures/nested-agent-conflict-session.jsonl: Add explicit-vs-path conflict agent fixture. - tests/fixtures/nested-agent-session.jsonl: Add nested linked agent fixture. - tests/fixtures/nested-main-session.jsonl: Add nested parent session fixture with unresolved references. - tests/fixtures/performance/perf-main-session-001.jsonl: Add first performance fixture session. - tests/fixtures/performance/perf-main-session-101.jsonl: Add 101st performance fixture session. - tests/helpers/agent-linking.ts: Add shared helpers for temporary Claude fixture trees. - tests/integration/cli/view.test.ts: Cover direct agent lookup, ambiguity JSON, and missing-agent JSON behavior. - tests/integration/contract/claude-session-contract.test.ts: Verify anonymized nested Claude contract parsing and lookup. - tests/integration/export-sessions.test.ts: Verify export metadata round-trips and no project-wide agent guessing. - tests/integration/get-session.test.ts: Cover nested, fallback, conflict, duplicate, and legacy flat-agent retrieval. - tests/integration/list-sessions.test.ts: Ensure top-level lists stay main-session-only with scoped agent metadata. - tests/integration/performance/session-lookup.test.ts: Add 100+ session list/get/view performance validation. - tests/unit/cli/commands/view.test.ts: Update mocked sessions and assert direct agent lookup error payloads. - tests/unit/cli/formatters/session.test.ts: Verify linked and unresolved metadata rendering. - tests/unit/parser.test.ts: Cover explicit child-agent reference extraction from multiple raw shapes. - tests/unit/platform.test.ts: Cover recursive discovery and nested owner parsing across path variants.
Promote the release version to 0.7.0 because the nested agent-session work is an additive feature release with new metadata fields, direct agent lookup semantics, and structured CLI error behavior, not a patch-only bugfix. Apply Prettier output to the touched TypeScript files so the branch is fully formatted after the feature implementation commit. Validation performed: - npm run typecheck - npm test Per-file summaries: - package.json: Bump package version to 0.7.0. - package-lock.json: Sync root package and lockfile package versions to 0.7.0. - src/cli/commands/view.ts: Apply Prettier formatting to the direct agent lookup error branch. - src/cli/utils/errors.ts: Apply Prettier formatting to usage and not-found error helpers. - src/lib/platform.ts: Apply Prettier formatting to nested path helper signatures. - src/lib/session.ts: Apply Prettier formatting to link-resolution and lookup helpers. - tests/integration/cli/view.test.ts: Apply Prettier formatting to CLI ambiguity assertions. - tests/integration/performance/session-lookup.test.ts: Apply Prettier formatting to performance fixture setup and lookup timing checks.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
agent as tool issue #7