Skip to content

Conversation

JAORMX
Copy link
Collaborator

@JAORMX JAORMX commented Sep 15, 2025

This PR adds a new implementation-agnostic Runtime Authoring Guide.

Key points:

  • Defines a stable behavioral contract for new runtimes (capabilities, lifecycle, transports, permissions, isolation, labels, idempotency, error handling, observability, testing, security posture, performance, portability, and acceptance criteria).
  • Adds an appendix clarifying the runtime obligations for MCP_TRANSPORT and MCP_PORT (and compatible FASTMCP_PORT/MCP_HOST), including precedence and merge strategy, isolated vs non-isolated behaviors, and separation of internal MCP_PORT vs externally published host port.

Document path:

  • docs/runtime-implementation-guide.md

This should help future runtime authors implement consistent behavior across platforms while leaving room for platform-specific optimizations.

@JAORMX JAORMX changed the title docs: add Runtime Authoring Guide; document MCP_TRANSPORT/MCP_PORT contract docs: add Runtime Authoring Guide Sep 15, 2025
@JAORMX JAORMX force-pushed the docs/runtime-authoring-guide branch from 8064137 to e956dff Compare September 15, 2025 10:35
Copy link

codecov bot commented Sep 15, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 46.94%. Comparing base (b92b9e7) to head (1659d3d).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #1890      +/-   ##
==========================================
- Coverage   47.01%   46.94%   -0.08%     
==========================================
  Files         223      223              
  Lines       27659    27669      +10     
==========================================
- Hits        13005    12989      -16     
- Misses      13653    13684      +31     
+ Partials     1001      996       -5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@coveralls
Copy link
Collaborator

Coverage Status

coverage: 42.926% (+0.04%) from 42.885%
when pulling e956dff on docs/runtime-authoring-guide
into 736602f on main.

@coveralls
Copy link
Collaborator

Coverage Status

coverage: 42.882% (-0.003%) from 42.885%
when pulling e956dff on docs/runtime-authoring-guide
into 736602f on main.

- If attachStdio=true, enable interactive session wiring where platform supports it (does not impact return semantics).
- Return 0 for stdio transport, or the published host port for SSE/Streamable HTTP.

List
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is List part of the workload lifecycle? We have a similar section on listing above in the Runtime contract section, I wonder if we need it in both places.

…ntract

Signed-off-by: Juan Antonio Osorio <ozz@stacklok.com>
@JAORMX JAORMX force-pushed the docs/runtime-authoring-guide branch from e956dff to 1659d3d Compare September 18, 2025 10:21
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.

4 participants