Skip to content

Add IntentCall runtime session package#2

Merged
Arenukvern merged 1 commit into
mainfrom
chore/adopt-steward-governance
Jun 22, 2026
Merged

Add IntentCall runtime session package#2
Arenukvern merged 1 commit into
mainfrom
chore/adopt-steward-governance

Conversation

@Arenukvern

@Arenukvern Arenukvern commented Jun 22, 2026

Copy link
Copy Markdown
Owner

Summary

  • add intentcall_session for runtime session lifecycle, file-backed state, safe writes, locks, session execution, and JSON snapshot storage
  • move tool/resource/resource-template registration value objects into intentcall_core so adapters consume one canonical API
  • update MCP publishing to expose static resources as query-tolerant templates and de-duplicate template patterns
  • document the ownership boundary: sessions live in IntentCall, dynamic registry/invocation stays with IntentCall, Flutter-specific transports stay in consumers/adapters

Validation

  • dart analyze packages/intentcall_core packages/intentcall_mcp packages/intentcall_session tool/intentcall
  • dart test packages/intentcall_session/test packages/intentcall_mcp/test/mcp_publish_adapter_test.dart
  • steward probe --json --profile quick

Related

Summary by CodeRabbit

  • New Features

    • Introduced new session package providing runtime session lifecycle management, file-backed state persistence, connection diagnostics, and safe file operations
    • Exported shared registration helpers for resources, templates, and tools from core package for use across integrations
  • Documentation

    • Added comprehensive session usage documentation with code examples and API references
    • Updated package READMEs and decision records describing session architecture and boundaries

@docs-page

docs-page Bot commented Jun 22, 2026

Copy link
Copy Markdown

To preview the documentation for this pull request, visit the following URL:

docs.page/arenukvern/intentcall~2

Documentation is deployed and generated using docs.page

@coderabbitai

coderabbitai Bot commented Jun 22, 2026

Copy link
Copy Markdown

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3e8dddb1-1b94-40dc-b559-f3dab82922c4

📥 Commits

Reviewing files that changed from the base of the PR and between 9291b2e and 10693b0.

⛔ Files ignored due to path filters (1)
  • pubspec.lock is excluded by !**/*.lock
📒 Files selected for processing (45)
  • .github/workflows/ci.yml
  • PUBLISHING.md
  • README.md
  • docs/DESIGN_FAQ.mdx
  • docs/DX_FAQ.mdx
  • docs/decisions/0014-own-runtime-sessions-in-intentcall.md
  • docs/decisions/README.md
  • justfile
  • packages/intentcall_core/README.md
  • packages/intentcall_core/lib/intentcall_core.dart
  • packages/intentcall_core/lib/src/authoring/agent_call_entry.dart
  • packages/intentcall_core/lib/src/intent/registered_agent_intent.dart
  • packages/intentcall_core/lib/src/naming/qualified_name.dart
  • packages/intentcall_core/lib/src/registration/resource_registration.dart
  • packages/intentcall_core/lib/src/registration/resource_template_registration.dart
  • packages/intentcall_core/lib/src/registration/tool_registration.dart
  • packages/intentcall_mcp/README.md
  • packages/intentcall_mcp/lib/src/agent_bridge.dart
  • packages/intentcall_mcp/lib/src/mcp_publish_adapter.dart
  • packages/intentcall_mcp/lib/src/resource_registration.dart
  • packages/intentcall_mcp/lib/src/resource_template_registration.dart
  • packages/intentcall_mcp/lib/src/tool_registration.dart
  • packages/intentcall_mcp/test/mcp_publish_adapter_test.dart
  • packages/intentcall_session/CHANGELOG.md
  • packages/intentcall_session/LICENSE
  • packages/intentcall_session/README.md
  • packages/intentcall_session/analysis_options.yaml
  • packages/intentcall_session/lib/intentcall_session.dart
  • packages/intentcall_session/lib/src/agent_session_executor.dart
  • packages/intentcall_session/lib/src/json_helpers.dart
  • packages/intentcall_session/lib/src/safe_writes.dart
  • packages/intentcall_session/lib/src/session_connector.dart
  • packages/intentcall_session/lib/src/session_manager.dart
  • packages/intentcall_session/lib/src/session_requests.dart
  • packages/intentcall_session/lib/src/snapshot_store.dart
  • packages/intentcall_session/lib/src/state_lock_manager.dart
  • packages/intentcall_session/lib/src/state_store.dart
  • packages/intentcall_session/pubspec.yaml
  • packages/intentcall_session/test/agent_session_executor_test.dart
  • packages/intentcall_session/test/session_manager_test.dart
  • packages/intentcall_session/test/snapshot_store_test.dart
  • packages/intentcall_session/test/state_store_test.dart
  • pubspec.yaml
  • release-please-config.json
  • tool/intentcall/bin/intentcall.dart

📝 Walkthrough

Walkthrough

A new intentcall_session Dart package is introduced, providing file-backed session persistence (StateStore), file-based mutual exclusion (StateLockManager), safe atomic file writes (SafeFileWriter), session lifecycle management (IntentSessionManager), a registry executor (IntentSessionExecutor), and JSON snapshot diffing (IntentSnapshotStore). Concurrently, resource and tool registration types are moved from intentcall_mcp into intentcall_core, and the MCP publish adapter gains URI-template deduplication. The package is wired into the workspace, release configuration, tooling, and documentation.

Changes

IntentCall Session Package and Registration Type Migration

Layer / File(s) Summary
Registration types promoted to intentcall_core
packages/intentcall_core/lib/src/registration/resource_registration.dart, packages/intentcall_core/lib/src/registration/resource_template_registration.dart, packages/intentcall_core/lib/src/registration/tool_registration.dart, packages/intentcall_core/lib/intentcall_core.dart, packages/intentcall_mcp/lib/src/resource_registration.dart, packages/intentcall_mcp/lib/src/resource_template_registration.dart, packages/intentcall_mcp/lib/src/tool_registration.dart, packages/intentcall_mcp/lib/src/agent_bridge.dart
ResourceRegistration, ResourceTemplateRegistration, and ToolRegistration with their handler typedefs are added as source files under intentcall_core and exported from its barrel. The three intentcall_mcp registration files become thin re-export shims. Minor reformatting in existing core files accompanies this.
MCP adapter: URI template deduplication and tests
packages/intentcall_mcp/lib/src/mcp_publish_adapter.dart, packages/intentcall_mcp/test/mcp_publish_adapter_test.dart, packages/intentcall_mcp/README.md
Adds _publishedResourceTemplatePatterns set to McpPublishAdapter and early-return guards that prevent re-publishing templates sharing the same URI pattern. Resource-intent publishing now uses matchUriTemplate for param extraction. Two new tests verify static resource + query-tolerant template publishing and template de-duplication by URI pattern.
Session package: file-backed persistence foundation
packages/intentcall_session/lib/src/state_lock_manager.dart, packages/intentcall_session/lib/src/safe_writes.dart, packages/intentcall_session/lib/src/state_store.dart, packages/intentcall_session/lib/src/json_helpers.dart
Introduces StateLockManager with exclusive file locking, stale-lock recovery, and configurable timeouts. SafeFileWriter performs atomic temp-file-rename writes with write-status tracking, unified diff metadata, timestamped backup, and check-only mode. StateStore serializes PersistedState/SessionState as pretty-printed JSON with chmod 600 and lock coordination. jsonObjectOrEmpty normalizes inputs to Map<String, Object?>.
Session package: connector contract, requests, and manager
packages/intentcall_session/lib/src/session_connector.dart, packages/intentcall_session/lib/src/session_requests.dart, packages/intentcall_session/lib/src/session_manager.dart
Defines IntentSessionConnector interface, IntentSessionConnectionException/failure reason constants, IntentSessionConnectionMode enum, IntentSessionErrorCode string constants, and IntentSessionStartRequest/IntentSessionAttachRequest value objects. IntentSessionManager implements start, attach, end, and mark-used operations over StateStore with full error-code mapping.
Session package: snapshot store and executor
packages/intentcall_session/lib/src/snapshot_store.dart, packages/intentcall_session/lib/src/agent_session_executor.dart
IntentSnapshotStore saves/loads/lists/diffs JSON snapshots via SafeFileWriter; its recursive _diffNode engine classifies added/removed/type_changed/changed nodes across maps and lists. IntentSessionExecutor attaches a session before invoking an AgentRegistry entry and marks the session used on success.
Session package scaffolding, tests, and project wiring
packages/intentcall_session/lib/intentcall_session.dart, packages/intentcall_session/pubspec.yaml, packages/intentcall_session/analysis_options.yaml, packages/intentcall_session/..., packages/intentcall_session/test/*, pubspec.yaml, release-please-config.json, tool/intentcall/bin/intentcall.dart, justfile, .github/workflows/ci.yml
Adds the library barrel, package metadata files, and test suites for StateStore, IntentSessionManager, IntentSessionExecutor, and IntentSnapshotStore (using in-memory fake connectors and temporary state paths). Registers the package in workspace, release config, publish order, and CI test command.
ADR, FAQs, and documentation
docs/decisions/0014-own-runtime-sessions-in-intentcall.md, docs/decisions/README.md, docs/DESIGN_FAQ.mdx, docs/DX_FAQ.mdx, README.md, PUBLISHING.md, packages/intentcall_core/README.md
ADR 0014 records the decision to own runtime sessions in intentcall_session and defines explicit inclusion/exclusion boundaries. DESIGN_FAQ.mdx and DX_FAQ.mdx gain runtime sessions sections with usage examples and testing guidance. Root README.md, PUBLISHING.md, and intentcall_core/README.md reference the new package.

Sequence Diagram

sequenceDiagram
  participant Host
  participant IntentSessionExecutor
  participant IntentSessionManager
  participant IntentSessionConnector
  participant StateStore
  participant AgentRegistry

  Host->>IntentSessionExecutor: invoke(qualifiedName, sessionId, arguments)
  IntentSessionExecutor->>IntentSessionManager: attachSession(sessionId)
  IntentSessionManager->>IntentSessionConnector: connect(endpoint, forceReconnect)
  IntentSessionConnector-->>IntentSessionManager: connection result
  IntentSessionManager->>StateStore: withStateLock → markSessionUsed + writeUnlocked
  IntentSessionManager-->>IntentSessionExecutor: AgentResult (attach)
  alt attach failed
    IntentSessionExecutor-->>Host: AgentResult.failure(connectFailed)
  else attach succeeded
    IntentSessionExecutor->>AgentRegistry: invoke(qualifiedName, arguments)
    AgentRegistry-->>IntentSessionExecutor: AgentResult
    IntentSessionExecutor->>IntentSessionManager: markSessionUsed(sessionId)
    IntentSessionExecutor-->>Host: AgentResult
  end
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐇 A new package hops in, intentcall_session it's named,
With file locks and safe writes, the state tamed!
Sessions start, attach, and end with a snap,
Snapshots are diffed — no regression mishap.
Types moved to core, the MCP deduped neat,
This rabbit declares: the architecture's complete! 🥕

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch chore/adopt-steward-governance

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@Arenukvern Arenukvern marked this pull request as ready for review June 22, 2026 21:54
@Arenukvern Arenukvern merged commit 495b419 into main Jun 22, 2026
1 of 2 checks passed
@Arenukvern Arenukvern deleted the chore/adopt-steward-governance branch June 22, 2026 21:54
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