Documentation
¶
Overview ¶
Package scriptsession is the production Caller a managed script's run issues its platform calls through: one in-memory MCP session against the fully assembled server, and the reading of a failed result as the refusal the engine paces on (#1419). Extracted from internal/platform/scriptrun so the engine holds the interpreter and its bindings, and the session plumbing is visibly a second thing.
Index ¶
Constants ¶
const TextResultKey = "text"
TextResultKey is the single field a tool result arrives under when the tool returned no structured object: the text it produced, verbatim (SessionCaller.CallTool).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type RefusalError ¶
type RefusalError struct {
Code string
RetryAfter time.Duration
// Text is the result's own text, what Error returns.
Text string
}
RefusalError is a tool call that failed with the platform's structured error envelope ({code, category, message, hint, retry_after_seconds}), returned by a Caller as the error so the engine can read the refusal as data. Its Error text is what the script would have been handed before the envelope was read: the result's own text, so a failure the engine does not absorb reaches the author in the tool's words.
The engine acts on exactly one code, toolratelimit.CodeRateLimited, and passes every other refusal through unchanged.
func (*RefusalError) Error ¶
func (r *RefusalError) Error() string
Error returns the refusal's text as the tool wrote it.
type SessionCaller ¶
type SessionCaller struct {
// contains filtered or unexported fields
}
SessionCaller issues a script's platform calls over one in-memory MCP session against the fully assembled server. It is the production Caller: every host binding a script invokes becomes an ordinary tool call, crossing the same authentication, authorization, gate, rate-limit, and audit middleware an agent's call crosses, with no second implementation to keep in step.
func Connect ¶
Connect opens an in-memory MCP session against server and returns the SessionCaller that drives it, plus the teardown for both ends. Both call sites hand it straight to scriptrun.Options.Caller.
The identity the session authenticates as comes from ctx, which the caller has already decorated: a draft run carries its author's own identity, a platform run carries the script principal and the version author's captured roles. This function deliberately establishes no identity of its own — there is one place a script's authority is decided, and it is not here. label names the client in the handshake so the two run kinds are distinguishable in logs.
func (*SessionCaller) CallTool ¶
func (c *SessionCaller) CallTool(ctx context.Context, name string, args map[string]any) (map[string]any, error)
CallTool invokes one tool and returns its structured content. A tool that reports an error through the platform's envelope is returned as a *RefusalError, so the engine can pace a rate-limit refusal; the error's text is the result's own either way.
func (*SessionCaller) DeclaresReadOnly ¶
func (c *SessionCaller) DeclaresReadOnly(ctx context.Context, name string) (readOnly, known bool)
DeclaresReadOnly reports whether the server this session is connected to advertises the named tool with MCP's read-only annotation, and whether it advertises the tool at all.
It is the one thing the platform knows about a tool no classification rule names: an MCP gateway connection proxies whatever its upstream serves, under names the upstream chose, and the upstream's own ReadOnlyHint travels with the tool onto this server's listing. The draft's write barrier takes that statement rather than refusing every proxied tool (#1664).
The listing is the SESSION's, so it is already filtered to what this run may see. The annotation is a plain bool in the protocol, so "declared false" and "declared nothing" are one value; only true is a statement, which is why it is the only value that answers read.
Source Files