fix: update foundry-agent invoke skill for invocations protocol

[Kishore B R (Kishore712)]

Summary

Update the foundry-agent invoke skill to clearly document how the invocations protocol works — the platform is pure pass-through, input and output are raw bytes defined by the container developer.

Changes

invoke.md

• Updated Protocols section: explicitly states invocations is bytes in, bytes out with no platform transformation
• Updated Step 3: added OpenAPI spec discovery as the preferred method to learn expected input format
• Updated Step 4: clarified conversationId and stream do not apply to invocations
• Added schema mismatch error to Error Handling table

New references/invocations-protocol.md

• Full I/O contract comparison table (responses vs invocations)
• 3-step schema discovery workflow: fetch OpenAPI spec → inspect source code → ask user
• Documents the GET .../invocations/docs/openapi.json endpoint
• Concrete examples for both protocols
• Common use cases and error handling

Motivation

The invoke skill previously gave vague guidance for the invocations protocol ("payload shape depends on what the hosted agent code expects"). This caused confusion during local testing — agents need clear instructions that invocations is raw bytes pass-through and how to discover the expected input format.

Validation

• ✅ npm run build — passes
• ✅ npm run tokens check — within limits
• ✅ npm run references — no broken/orphaned references
• ✅ All 32 invoke skill tests pass (unit + triggers)

[Copilot]

Pull request overview

This PR updates the microsoft-foundry skill documentation to clarify how the hosted-agent invocations protocol works (raw bytes pass-through) and expands the invoke workflow guidance around sessions and file operations.

Changes:

• Clarifies invocations as “bytes in, bytes out” and adds a schema-discovery workflow (prefer OpenAPI).
• Adds new invoke reference docs for session management, invocations protocol details, and session file operations.
• Updates skill routing links and unit tests to reflect renamed/updated create + invoke documentation.

Reviewed changes

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

Show a summary per file

File	Description
tests/microsoft-foundry/foundry-agent/invoke/unit.test.ts	Updates assertions to match the new invoke docs (sessions vs sticky-session wording).
tests/microsoft-foundry/foundry-agent/create/unit.test.ts	Updates the test to load create-hosted.md instead of the prior create.md path.
plugin/skills/microsoft-foundry/SKILL.md	Updates the create sub-skill link and lifecycle routing to point to create-hosted.md.
plugin/skills/microsoft-foundry/foundry-agent/invoke/invoke.md	Reworks invoke guidance: protocols, sessions via session_create, file ops, and updated error handling.
plugin/skills/microsoft-foundry/foundry-agent/invoke/references/session-management.md	New detailed reference for session lifecycle, tooling, and session vs conversation semantics.
plugin/skills/microsoft-foundry/foundry-agent/invoke/references/invocations-protocol.md	New reference explaining invocations I/O contract, schema discovery, examples, and errors.
plugin/skills/microsoft-foundry/foundry-agent/invoke/references/file-operations.md	New reference for session file tooling and common upload/invoke/download patterns.
plugin/skills/microsoft-foundry/foundry-agent/create/create-prompt.md	Updates cross-link to the hosted-agent create doc (create-hosted.md).
plugin/skills/microsoft-foundry/foundry-agent/create/create-hosted.md	Adds guidance on reserved, platform-injected environment variables for hosted agents.

[Jon Gallant (jongio)]

Solid documentation restructuring. The invoke skill now clearly separates the two protocols and properly delegates session management and file operations to reference docs. The rename from create.md to create-hosted.md is handled cleanly with all cross-references updated.

One observation the bot review didn't catch: the old az rest fallback for invocations is removed, but the inline workflow (Step 3) doesn't show a concrete agent_invoke call with protocol: 'invocations'. The example lives in references/invocations-protocol.md, which is fine for progressive disclosure - but a one-liner example or snippet in Step 3 itself (where users will first encounter invocations guidance) would reduce the back-and-forth for someone following the workflow linearly.

The Quick Reference conversation row inconsistency (already flagged) is the only real issue - the rest reads well.

[Jon Gallant (jongio)]

Addresses all prior feedback cleanly. The inline invocations example in Step 3, clarified Quick Reference row, and documented FOUNDRY_* variables all look correct. The test assertion is now precise. No new issues.