Transaction Preview
transaction-preview · Query · Server · Transactions
Previews the current staged transaction.
Availability: Published only in transactional and autonomous-trusted operational modes.
Generated from Roslyn Workbench MCP 1.0.1 (1.0.1).
Behaviour annotations
| Annotation | Value |
|---|---|
destructiveHint |
false |
idempotentHint |
true |
openWorldHint |
false |
readOnlyHint |
true |
title |
"Transaction Preview" |
Request
| Property | Type | Required | Description |
|---|---|---|---|
document |
object | null |
No | Document whose detailed diff should be returned; provide it when includeDiff is true. |
includeDiff |
boolean |
No | Whether to include a detailed diff. |
contextLines |
integer |
No | Number of unchanged context lines around each diff hunk when includeDiff is true. |
workspace |
object | null |
No | Provide workspaceId, alias, path, or any combination. |
Response
Success response
| Property | Type | Required | Description |
|---|---|---|---|
ok |
boolean constant (true) |
Yes | Whether the tool invocation succeeded. |
data |
object | null |
Yes | Tool-specific result payload. |
snapshot |
object |
No | Exact immutable workspace snapshot associated with the result, when available. |
warnings |
array |
No | Non-fatal warnings the agent should consider. |
Error response
| Property | Type | Required | Description |
|---|---|---|---|
ok |
boolean constant (false) |
Yes | Whether the tool invocation succeeded. |
error |
object |
Yes | Structured error details when the invocation failed. |
continuation |
oneOf |
No | Action the agent should take before retrying or continuing. |
diagnostics |
array |
No | Diagnostics that explain the failed invocation. |
warnings |
array |
No | Non-fatal warnings the agent should consider. |
Error response
| Property | Type | Required | Description |
|---|---|---|---|
ok |
boolean constant (false) |
Yes | Whether the tool invocation succeeded. |
error |
object |
Yes | Structured error details when the invocation failed. |
diagnostics |
object |
Yes | Diagnostics that explain the failed invocation. |
reporting |
object |
No | Error-reporting workflow available for an unhandled failure. |
Continuations and required actions
A response may include a structured continuation at the following schema location. Follow its tool call or user-action instruction instead of guessing how to continue:
$/oneOf/1/properties/continuation
Examples
Preview staged changes
Workflow: Stage, review and commit one change, step 3.
Operational modes: transactional, autonomous-trusted.
Inspect a focused diff before deciding whether to commit or roll back the transaction.
Expected outcome: A three-line-context diff is returned for the selected document without writing files.
{
"document": {
"path": "src/Sample.cs"
},
"includeDiff": true,
"contextLines": 3,
"workspace": {
"alias": "sample"
}
}
Complete input schema
{
"type": "object",
"properties": {
"document": {
"description": "Document whose detailed diff should be returned; provide it when includeDiff is true.",
"type": [
"object",
"null"
],
"properties": {
"project": {
"description": "Disambiguates documents with matching paths or IDs.",
"type": [
"object",
"null"
],
"properties": {
"projectId": {
"type": "string"
},
"name": {
"type": "string"
},
"path": {
"description": "Workspace-relative path.",
"type": "string"
},
"targetFramework": {
"type": "string"
}
}
},
"path": {
"description": "Workspace-relative path.",
"type": "string"
},
"documentId": {
"description": "Workspace-local document ID.",
"type": "string"
}
}
},
"includeDiff": {
"description": "Whether to include a detailed diff.",
"type": "boolean"
},
"contextLines": {
"description": "Number of unchanged context lines around each diff hunk when includeDiff is true.",
"type": "integer",
"minimum": 0,
"maximum": 2147483647,
"default": 3
},
"workspace": {
"description": "Provide workspaceId, alias, path, or any combination.",
"type": [
"object",
"null"
],
"properties": {
"workspaceId": {
"type": "string",
"format": "uuid"
},
"alias": {
"type": "string"
},
"path": {
"description": "Absolute workspace path.",
"type": "string"
}
}
}
}
}
Complete output schema
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"ok",
"data"
],
"properties": {
"ok": {
"const": true,
"description": "Whether the tool invocation succeeded."
},
"data": {
"type": [
"object",
"null"
],
"properties": {
"transaction": {
"description": "The active transaction info.",
"type": [
"object",
"null"
],
"properties": {
"revision": {
"description": "Current staged transaction revision.",
"type": "integer"
},
"revisionCount": {
"description": "Number of revisions retained in transaction history.",
"type": "integer"
},
"maxRevisions": {
"description": "Maximum number of revisions the transaction can retain.",
"type": "integer"
},
"remainingRevisions": {
"description": "Number of additional revisions that can be staged.",
"type": "integer"
},
"canMutate": {
"description": "Whether mutation tools may stage another change.",
"type": "boolean"
},
"canUndo": {
"description": "Whether transaction history can move to the preceding revision.",
"type": "boolean"
},
"canRedo": {
"description": "Whether transaction history can move to the following revision.",
"type": "boolean"
},
"canCommit": {
"description": "Whether the staged transaction can be committed to disk.",
"type": "boolean"
},
"canRollback": {
"description": "Whether the complete staged transaction can be discarded.",
"type": "boolean"
}
}
},
"documents": {
"description": "The changed documents in the preview.",
"type": "array",
"items": {
"type": "object",
"properties": {
"document": {
"description": "The document that changed.",
"type": [
"object",
"null"
],
"properties": {
"documentId": {
"description": "The document identifier.",
"type": "string"
},
"path": {
"description": "The normalized document path.",
"type": "string"
},
"projectId": {
"description": "The owning project identifier.",
"type": "string"
}
},
"required": [
"documentId",
"path",
"projectId"
]
},
"changeKind": {
"description": "The kind of change applied to the document.",
"type": "string",
"enum": [
"Added",
"Modified",
"Deleted"
]
},
"preview": {
"description": "The optional diff summary for the change.",
"type": [
"object",
"null"
],
"properties": {
"addedLines": {
"description": "The number of added lines.",
"type": "integer"
},
"removedLines": {
"description": "The number of removed lines.",
"type": "integer"
},
"changedLines": {
"description": "The number of changed lines.",
"type": "integer"
}
}
}
}
}
},
"provenance": {
"description": "Mutation revisions contributing to the previewed transaction.",
"type": "array",
"items": {
"type": "object",
"properties": {
"revision": {
"description": "One-based transaction revision.",
"type": "integer"
},
"operation": {
"description": "Mutation operation recorded for the revision.",
"type": "string"
},
"summary": {
"description": "Concise mutation summary recorded for the revision.",
"type": "string"
},
"codeAction": {
"description": "Code Action attribution when this revision was produced by a Code Action.",
"type": [
"object",
"null"
],
"properties": {
"kind": {
"description": "Code Action family that produced the mutation.",
"type": "string",
"enum": [
"CodeFix",
"Refactoring",
"FixAll"
]
},
"providerId": {
"description": "Response-local reference to the provider that originated the Code Action.",
"type": "string"
},
"fixAllProviderId": {
"description": "Response-local reference to the Fix All provider when one assembled the operation.",
"type": [
"string",
"null"
]
}
},
"required": [
"kind",
"providerId"
]
}
},
"required": [
"revision",
"operation",
"summary"
]
}
},
"providers": {
"description": "Provider identities keyed by response-local references used by provenance entries.",
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "object",
"properties": {
"typeName": {
"description": "Fully qualified runtime type of the provider that supplied the mutation.",
"type": "string"
},
"assemblyName": {
"description": "Simple name of the assembly containing the provider.",
"type": "string"
},
"assemblyVersion": {
"description": "Version of the assembly containing the provider.",
"type": "string"
}
},
"required": [
"typeName",
"assemblyName",
"assemblyVersion"
]
}
},
"diff": {
"description": "The optional detailed diff.",
"type": [
"object",
"null"
],
"properties": {
"document": {
"description": "Document for which the detailed diff was produced.",
"type": [
"object",
"null"
],
"properties": {
"documentId": {
"description": "The document identifier.",
"type": "string"
},
"path": {
"description": "The normalized document path.",
"type": "string"
},
"projectId": {
"description": "The owning project identifier.",
"type": "string"
}
},
"required": [
"documentId",
"path",
"projectId"
]
},
"hunks": {
"description": "Changed regions in unified-diff form.",
"type": "array",
"items": {
"type": "object",
"properties": {
"originalStartLine": {
"description": "One-based starting line in the original document.",
"type": "integer"
},
"originalLineCount": {
"description": "Number of original-document lines covered by the hunk.",
"type": "integer"
},
"updatedStartLine": {
"description": "One-based starting line in the updated document.",
"type": "integer"
},
"updatedLineCount": {
"description": "Number of updated-document lines covered by the hunk.",
"type": "integer"
},
"lines": {
"description": "Unified-diff content lines prefixed with space, +, or -.",
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"truncated": {
"description": "Whether one or more diff hunks were omitted from the response.",
"type": "boolean"
}
}
}
},
"description": "Tool-specific result payload."
},
"snapshot": {
"type": "object",
"properties": {
"workspaceId": {
"type": "string",
"format": "uuid"
},
"workspaceEpoch": {
"type": "integer"
},
"snapshotId": {
"type": "string",
"format": "uuid"
},
"transactionRevision": {
"type": [
"integer",
"null"
]
}
},
"required": [
"workspaceId",
"workspaceEpoch",
"snapshotId",
"transactionRevision"
],
"description": "Exact immutable workspace snapshot associated with the result, when available."
},
"warnings": {
"type": "array",
"description": "Non-fatal warnings the agent should consider.",
"items": {
"$ref": "#/$defs/warningInfo"
}
}
}
},
{
"type": "object",
"required": [
"ok",
"error"
],
"properties": {
"ok": {
"const": false,
"description": "Whether the tool invocation succeeded."
},
"error": {
"type": "object",
"properties": {
"code": {
"description": "Stable machine-readable error code.",
"type": "string"
},
"message": {
"description": "Human-readable explanation of the failure.",
"type": "string"
},
"correlationId": {
"description": "Correlation identifier for matching the failure to server-side diagnostics, when available.",
"type": [
"string",
"null"
]
}
},
"required": [
"code",
"message"
],
"description": "Structured error details when the invocation failed."
},
"continuation": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"tool",
"instruction"
],
"properties": {
"kind": {
"const": "CallTool",
"description": "Action required before the original request can continue."
},
"instruction": {
"type": "string",
"description": "Agent-facing instruction explaining how to continue.",
"minLength": 1
},
"tool": {
"type": "string",
"description": "Tool to call before continuing the original request.",
"minLength": 1
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"tools",
"instruction"
],
"properties": {
"kind": {
"const": "ChooseTool",
"description": "Action required before the original request can continue."
},
"instruction": {
"type": "string",
"description": "Agent-facing instruction explaining how to continue.",
"minLength": 1
},
"tools": {
"type": "array",
"description": "Allowed tool choices from which the agent must select one.",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"description": "Name of a tool the agent may choose.",
"minLength": 1
}
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"instruction"
],
"properties": {
"kind": {
"const": "RetryRequest",
"description": "Action required before the original request can continue."
},
"instruction": {
"type": "string",
"description": "Agent-facing instruction explaining how to continue.",
"minLength": 1
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"instruction"
],
"properties": {
"kind": {
"const": "ReviseRequest",
"description": "Action required before the original request can continue."
},
"instruction": {
"type": "string",
"description": "Agent-facing instruction explaining how to continue.",
"minLength": 1
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"instruction"
],
"properties": {
"kind": {
"const": "ResolveExternally",
"description": "Action required before the original request can continue."
},
"instruction": {
"type": "string",
"description": "Agent-facing instruction explaining how to continue.",
"minLength": 1
}
}
}
],
"description": "Action the agent should take before retrying or continuing."
},
"diagnostics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "The diagnostic identifier.",
"type": "string"
},
"severity": {
"description": "The diagnostic severity.",
"type": "string",
"enum": [
"Hidden",
"Info",
"Warning",
"Error"
]
},
"message": {
"description": "The diagnostic message.",
"type": "string"
},
"location": {
"description": "The optional source location of the diagnostic.",
"type": [
"object",
"null"
],
"properties": {
"document": {
"description": "The resolved document.",
"type": [
"object",
"null"
],
"properties": {
"documentId": {
"description": "The document identifier.",
"type": "string"
},
"path": {
"description": "The normalized document path.",
"type": "string"
},
"projectId": {
"description": "The owning project identifier.",
"type": "string"
}
},
"required": [
"documentId",
"path",
"projectId"
]
},
"span": {
"description": "The resolved text span.",
"type": [
"object",
"null"
],
"properties": {
"start": {
"description": "Zero-based UTF-16 offset.",
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"length": {
"description": "UTF-16 code-unit length.",
"type": "integer",
"minimum": 0,
"maximum": 2147483647
}
}
},
"line": {
"description": "The one-based line number.",
"type": "integer"
},
"column": {
"description": "The one-based column number.",
"type": "integer"
},
"snapshot": {
"description": "The exact immutable workspace snapshot associated with this location.",
"type": "object",
"properties": {
"workspaceId": {
"type": "string",
"format": "uuid"
},
"workspaceEpoch": {
"type": "integer"
},
"snapshotId": {
"type": "string",
"format": "uuid"
},
"transactionRevision": {
"type": [
"integer",
"null"
]
}
},
"required": [
"workspaceId",
"workspaceEpoch",
"snapshotId",
"transactionRevision"
]
},
"selector": {
"description": "The canonical selector that can resolve this source location again.",
"type": [
"object",
"null"
],
"properties": {
"span": {
"type": "object",
"properties": {
"document": {
"description": "Provide exactly one of path or documentId.",
"type": "object",
"properties": {
"project": {
"description": "Disambiguates documents with matching paths or IDs.",
"type": [
"object",
"null"
],
"properties": {
"projectId": {
"type": [
"string",
"null"
]
},
"name": {
"type": [
"string",
"null"
]
},
"path": {
"description": "Workspace-relative path.",
"type": [
"string",
"null"
]
},
"targetFramework": {
"type": [
"string",
"null"
]
}
}
},
"path": {
"description": "Workspace-relative path.",
"type": [
"string",
"null"
]
},
"documentId": {
"description": "Workspace-local document ID.",
"type": [
"string",
"null"
]
}
}
},
"range": {
"description": "Zero-based UTF-16 range.",
"type": "object",
"properties": {
"start": {
"description": "Zero-based UTF-16 offset.",
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"length": {
"description": "UTF-16 code-unit length.",
"type": "integer",
"minimum": 0,
"maximum": 2147483647
}
}
}
},
"required": [
"document",
"range"
]
}
},
"required": [
"span"
]
}
},
"required": [
"snapshot"
]
}
},
"required": [
"id",
"message"
]
},
"description": "Diagnostics that explain the failed invocation."
},
"warnings": {
"type": "array",
"description": "Non-fatal warnings the agent should consider.",
"items": {
"$ref": "#/$defs/warningInfo"
}
}
}
},
{
"type": "object",
"required": [
"ok",
"error",
"diagnostics"
],
"properties": {
"ok": {
"const": false,
"description": "Whether the tool invocation succeeded."
},
"error": {
"type": "object",
"required": [
"code",
"message",
"correlationId"
],
"properties": {
"code": {
"const": "UnhandledException"
},
"message": {
"const": "Tool execution failed."
},
"correlationId": {
"type": "string",
"format": "uuid"
}
},
"description": "Structured error details when the invocation failed."
},
"diagnostics": {
"type": "object",
"required": [
"detailsAvailable",
"detailsTool"
],
"properties": {
"detailsAvailable": {
"const": true
},
"detailsTool": {
"const": "get-error-details"
}
},
"description": "Diagnostics that explain the failed invocation."
},
"reporting": {
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": [
"Available",
"AlwaysApproved",
"DisabledByConfiguration",
"ApprovalUnavailable"
]
},
"canPrepare": {
"type": "boolean"
},
"prepareTool": {
"type": [
"string",
"null"
]
}
},
"required": [
"state"
],
"description": "Error-reporting workflow available for an unhandled failure."
}
}
}
],
"$defs": {
"warningInfo": {
"type": "object",
"properties": {
"code": {
"description": "The stable machine-readable warning code.",
"type": "string"
},
"message": {
"description": "The human-readable warning message.",
"type": "string"
}
},
"required": [
"code",
"message"
]
}
}
}