Skip to content

feat(agent-core): add session management tools - #456

Merged
WinterYukky merged 1 commit into
aws-samples:mainfrom
WinterYukky:feature/session-tool-enhancements-1787631867
Aug 25, 2026
Merged

feat(agent-core): add session management tools#456
WinterYukky merged 1 commit into
aws-samples:mainfrom
WinterYukky:feature/session-tool-enhancements-1787631867

Conversation

@WinterYukky

Copy link
Copy Markdown
Contributor

Summary

Adds five session-management tools to the agent-core tool registry, giving
agents first-class control over the session lifecycle and hierarchy.

Motivation

Multi-agent workflows need to inspect and manage the session tree at runtime:
complete a finished session, list children/descendants, move a session under
a new parent, and export diagnostics for debugging. These tools expose that
capability to the model with appropriate permission checks.

Changes

  • completeSession(sessionId) — mark a session complete and stop its worker.
    Top-level self-completion is guarded by a confirmation prompt; child sessions
    may only complete themselves.
  • confirmCompleteSession — confirm a guarded completeSession call (registered
    as a required tool).
  • listSessions — list sessions by scope (children / descendants / all)
    with an optional status filter (all / active / completed) and
    parent/self/top-level permission checks.
  • reparentSession — move a session under a new parent, with cycle detection
    and permission checks.
  • exportSessionDiagnostics — dump session metadata and message history to
    local JSON for debugging, optionally across the descendant tree.
  • Register the tools in tools/index.ts (confirmCompleteSession in requiredTools;
    the rest in optionalTools).

completeSession / confirmCompleteSession set agentStatus='completed', emit an
agentStatusUpdate webapp event, and stop the worker instance.

Testing

  • npm run build -w packages/agent-core (tsc) — pass
  • vitest run for the new tools — 31 passed (completeSession 9, confirmCompleteSession 5, listSessions 17)
  • full agent-core suite — 299 passed
  • prettier format:check (agent-core) — pass

Notes

  • reparentSession / listSessions / exportSessionDiagnostics build on session
    helpers already in lib/sessions (getChildSessions, getDescendantSessions,
    reparentSessions, getAllSessionsIncludingChildren).
  • A related confirmCreateAgent gate is intentionally left for a follow-up PR:
    it depends on the sub-agent (parentAgentId) evolution of the agent-management
    tools, which is not yet upstream.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Adds five session-management tools to the agent-core tool registry:

- completeSession(sessionId) — mark a session complete and stop its
  worker, with a confirmation guard for top-level self-completion
- confirmCompleteSession — confirm a guarded completeSession call
- listSessions — list sessions by scope (children / descendants / all)
  with an optional status filter and permission checks
- reparentSession — move a session under a new parent, with cycle
  detection and permission checks
- exportSessionDiagnostics — dump session metadata + message history to
  local JSON for debugging, optionally across the descendant tree

completeSession/confirmCompleteSession set agentStatus='completed', emit
an agentStatusUpdate webapp event, and stop the worker instance.
Tools are registered in requiredTools (confirmCompleteSession) and
optionalTools (the rest).
@WinterYukky
WinterYukky merged commit 56452eb into aws-samples:main Aug 25, 2026
8 checks passed
@WinterYukky
WinterYukky deleted the feature/session-tool-enhancements-1787631867 branch August 25, 2026 06:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant