sensorium-trace 0.18.2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sensorium/__init__.py +0 -0
- sensorium/__main__.py +4 -0
- sensorium/_c/rt/sensorium_c_rt.c +1446 -0
- sensorium/_typescript/package-lock.json +68 -0
- sensorium/_typescript/package.json +39 -0
- sensorium/_typescript/src/bindings.mjs +792 -0
- sensorium/_typescript/src/cap.mjs +227 -0
- sensorium/_typescript/src/capabilities.mjs +40 -0
- sensorium/_typescript/src/dbg.mjs +348 -0
- sensorium/_typescript/src/escape.mjs +351 -0
- sensorium/_typescript/src/focus.mjs +135 -0
- sensorium/_typescript/src/hook.mjs +127 -0
- sensorium/_typescript/src/index.mjs +1 -0
- sensorium/_typescript/src/naming.mjs +63 -0
- sensorium/_typescript/src/positions.mjs +37 -0
- sensorium/_typescript/src/probe.mjs +246 -0
- sensorium/_typescript/src/qualname.mjs +236 -0
- sensorium/_typescript/src/redact.mjs +711 -0
- sensorium/_typescript/src/register.mjs +15 -0
- sensorium/_typescript/src/resolve.mjs +260 -0
- sensorium/_typescript/src/rt.mjs +798 -0
- sensorium/_typescript/src/setup.mjs +11 -0
- sensorium/_typescript/src/tally.mjs +164 -0
- sensorium/_typescript/src/tasks.mjs +175 -0
- sensorium/_typescript/src/transform.mjs +800 -0
- sensorium/_typescript/src/vite.mjs +99 -0
- sensorium/c/__init__.py +8 -0
- sensorium/c/cc.py +612 -0
- sensorium/c/cli.py +60 -0
- sensorium/c/convert.py +669 -0
- sensorium/c/decode.py +300 -0
- sensorium/c/driver.py +365 -0
- sensorium/c/dwarf.py +706 -0
- sensorium/c/format.py +271 -0
- sensorium/c/pkg.py +187 -0
- sensorium/c/plan.py +277 -0
- sensorium/cli.py +140 -0
- sensorium/driver.py +47 -0
- sensorium/exit.py +33 -0
- sensorium/invocations.py +83 -0
- sensorium/limits.py +253 -0
- sensorium/mcp/__init__.py +0 -0
- sensorium/mcp/audit.py +162 -0
- sensorium/mcp/child.py +240 -0
- sensorium/mcp/cmd.py +101 -0
- sensorium/mcp/jsonrpc.py +172 -0
- sensorium/mcp/result.py +187 -0
- sensorium/mcp/schema.py +390 -0
- sensorium/mcp/server.py +493 -0
- sensorium/mcp/tools.py +299 -0
- sensorium/paths.py +80 -0
- sensorium/query/__init__.py +0 -0
- sensorium/query/caps.py +150 -0
- sensorium/query/dbg_dialects.py +64 -0
- sensorium/query/diff_cmd.py +748 -0
- sensorium/query/diff_notes.py +117 -0
- sensorium/query/exceptions_c.py +263 -0
- sensorium/query/exceptions_cmd.py +788 -0
- sensorium/query/exceptions_group.py +571 -0
- sensorium/query/exceptions_invocation.py +487 -0
- sensorium/query/exceptions_rust.py +683 -0
- sensorium/query/exceptions_typescript.py +688 -0
- sensorium/query/expr.py +606 -0
- sensorium/query/failures_cmd.py +306 -0
- sensorium/query/flow_cmd.py +778 -0
- sensorium/query/flow_report.py +128 -0
- sensorium/query/flow_values.py +195 -0
- sensorium/query/fmt.py +280 -0
- sensorium/query/frame_cmd.py +237 -0
- sensorium/query/grep_cmd.py +156 -0
- sensorium/query/help.py +18 -0
- sensorium/query/info_cmd.py +527 -0
- sensorium/query/info_rust.py +214 -0
- sensorium/query/info_typescript.py +261 -0
- sensorium/query/js_inspect.py +394 -0
- sensorium/query/moves.py +254 -0
- sensorium/query/redact_cmd.py +304 -0
- sensorium/query/refocus_cmd.py +661 -0
- sensorium/query/refocus_env.py +493 -0
- sensorium/query/refocus_facts.py +269 -0
- sensorium/query/refocus_licence.py +187 -0
- sensorium/query/refocus_report.py +327 -0
- sensorium/query/refocus_rust.py +537 -0
- sensorium/query/refocus_threads.py +197 -0
- sensorium/query/refocus_typescript.py +756 -0
- sensorium/query/refocus_world.py +666 -0
- sensorium/query/runs_cmd.py +213 -0
- sensorium/query/rust_debug.py +176 -0
- sensorium/query/sites.py +171 -0
- sensorium/query/tree_cmd.py +511 -0
- sensorium/query/tree_threads.py +168 -0
- sensorium/query/vocab.py +723 -0
- sensorium/query/watch_cmd.py +657 -0
- sensorium/record/__init__.py +0 -0
- sensorium/record/boot.py +797 -0
- sensorium/record/boot_io.py +141 -0
- sensorium/record/budget.py +135 -0
- sensorium/record/capture.py +433 -0
- sensorium/record/children.py +755 -0
- sensorium/record/children_merge.py +179 -0
- sensorium/record/elide.py +55 -0
- sensorium/record/fingerprint.py +26 -0
- sensorium/record/thread_starts.py +261 -0
- sensorium/record/tracer.py +798 -0
- sensorium/record/tracer_exc.py +199 -0
- sensorium/record/tracer_frames.py +618 -0
- sensorium/redact.py +304 -0
- sensorium/redact_content.py +156 -0
- sensorium/redact_key.py +317 -0
- sensorium/redact_store.py +502 -0
- sensorium/redact_values.py +433 -0
- sensorium/store/__init__.py +0 -0
- sensorium/store/db.py +284 -0
- sensorium/store/gc.py +360 -0
- sensorium/store/payloads.py +69 -0
- sensorium/store/reader.py +438 -0
- sensorium/store/writer.py +283 -0
- sensorium/ts/__init__.py +10 -0
- sensorium/ts/build.py +783 -0
- sensorium/ts/cli.py +130 -0
- sensorium/ts/driver.py +472 -0
- sensorium/ts/focus.py +146 -0
- sensorium/ts/harness.py +314 -0
- sensorium/ts/ingest.py +380 -0
- sensorium/ts/invocation.py +252 -0
- sensorium/ts/pkg.py +167 -0
- sensorium/ts/redaction.py +64 -0
- sensorium/ts/spool.py +168 -0
- sensorium/ts/truncation.py +81 -0
- sensorium/ts/wrapper.py +255 -0
- sensorium_trace-0.18.2.dist-info/METADATA +245 -0
- sensorium_trace-0.18.2.dist-info/RECORD +135 -0
- sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
- sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
- sensorium_trace-0.18.2.dist-info/licenses/LICENSE +21 -0
sensorium/mcp/cmd.py
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
"""`sensorium mcp`: the subcommand that starts the server.
|
|
2
|
+
|
|
3
|
+
Thin on purpose: the words the CLI prints about this server (P19), the
|
|
4
|
+
policy flags' validation, and the one variable the whole process tree
|
|
5
|
+
reads (P9). What the server DOES is `server.py`'s.
|
|
6
|
+
|
|
7
|
+
WHY THE IMPORTS ARE INSIDE `run` (D31). `mcp.tools` imports
|
|
8
|
+
`sensorium.cli` -- it reads `sensorium run`'s own parser to build
|
|
9
|
+
`record`'s schema (D7) -- and `cli` imports this module to register the
|
|
10
|
+
subcommand: at module level that is a cycle, inside the function it is
|
|
11
|
+
three imports that happen after both modules exist. It is also why
|
|
12
|
+
`mcp` is registered beside `ts` and not in `cli._QUERY_MODULES`, which
|
|
13
|
+
is walked at import time.
|
|
14
|
+
|
|
15
|
+
WHY A REFUSAL IS EXIT 2 AND ONE LINE. The caller is a launcher in an
|
|
16
|
+
MCP client's configuration, and what a launcher shows the user is
|
|
17
|
+
whatever the process said before it died. A cap of ten bytes would
|
|
18
|
+
answer every question with a truncation marker and a timeout of zero
|
|
19
|
+
would kill every call before it spawned: both are refusals to START, in
|
|
20
|
+
a CLI's words rather than JSON-RPC's -- there is no client yet. The
|
|
21
|
+
table is built here for the same reason: a command that has lost the
|
|
22
|
+
help text a tool description is made of must refuse before a thread
|
|
23
|
+
exists. `server.main` is then handed that one table.
|
|
24
|
+
"""
|
|
25
|
+
from __future__ import annotations
|
|
26
|
+
|
|
27
|
+
import os
|
|
28
|
+
import sys
|
|
29
|
+
from pathlib import Path
|
|
30
|
+
|
|
31
|
+
#: The three strings `sensorium --help` and `sensorium mcp --help`
|
|
32
|
+
#: print (P19). The description says what the surface IS: a reader who
|
|
33
|
+
#: has never seen MCP needs its shape in one sentence.
|
|
34
|
+
HELP = "serve the store to a model over the Model Context Protocol on stdio"
|
|
35
|
+
DESCRIPTION = ("One JSON-RPC message per line on stdin/stdout; every query "
|
|
36
|
+
"command except redact is a tool, and record, refocus and "
|
|
37
|
+
"record_c are tools only under --allow-run. Diagnostics go "
|
|
38
|
+
"to stderr.")
|
|
39
|
+
EPILOG = "exit: 0 at EOF or SIGTERM, 2 a refusal to start"
|
|
40
|
+
|
|
41
|
+
#: Below this a cap cannot hold a head, a tail and the marker between
|
|
42
|
+
#: them, so the answer would be all marker (see `result.cap`).
|
|
43
|
+
MIN_OUTPUT = 4096
|
|
44
|
+
DEFAULT_OUTPUT = 65536
|
|
45
|
+
DEFAULT_TIMEOUT = 60.0
|
|
46
|
+
DEFAULT_RUN_TIMEOUT = 600.0
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def add_parser(sub) -> None:
|
|
50
|
+
p = sub.add_parser("mcp", help=HELP, description=DESCRIPTION,
|
|
51
|
+
epilog=EPILOG)
|
|
52
|
+
p.add_argument("--allow-run", action="store_true",
|
|
53
|
+
help="offer record, refocus and record_c, the three "
|
|
54
|
+
"executing tools; default off")
|
|
55
|
+
p.add_argument("--store", default=None, metavar="DIR",
|
|
56
|
+
help="the trace store to serve, as SENSORIUM_DIR for "
|
|
57
|
+
"this server and every call it makes; default the "
|
|
58
|
+
"inherited store")
|
|
59
|
+
p.add_argument("--max-output", type=int, default=DEFAULT_OUTPUT,
|
|
60
|
+
metavar="BYTES", help="cap one answer's body at this "
|
|
61
|
+
"many bytes, head and tail kept with a marker naming "
|
|
62
|
+
f"what was cut; minimum {MIN_OUTPUT}")
|
|
63
|
+
p.add_argument("--timeout", type=float, default=DEFAULT_TIMEOUT,
|
|
64
|
+
metavar="SECONDS", help="how long one query tool may "
|
|
65
|
+
"take before its process group is killed and the call "
|
|
66
|
+
"is answered no answer")
|
|
67
|
+
p.add_argument("--run-timeout", type=float, default=DEFAULT_RUN_TIMEOUT,
|
|
68
|
+
metavar="SECONDS", help="the same bound for the three "
|
|
69
|
+
"tools that execute the recorded program, which are "
|
|
70
|
+
"expected to take longer")
|
|
71
|
+
p.set_defaults(func=run)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def _refuse(what: str) -> int:
|
|
75
|
+
print(f"sensorium mcp: {what}", file=sys.stderr)
|
|
76
|
+
return 2
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def run(args) -> int:
|
|
80
|
+
from sensorium.mcp import schema, server, tools # D31: the cycle
|
|
81
|
+
if args.max_output < MIN_OUTPUT:
|
|
82
|
+
return _refuse(f"--max-output {args.max_output} is below the "
|
|
83
|
+
f"{MIN_OUTPUT}-byte minimum")
|
|
84
|
+
for flag, seconds in (("--timeout", args.timeout),
|
|
85
|
+
("--run-timeout", args.run_timeout)):
|
|
86
|
+
if seconds <= 0:
|
|
87
|
+
return _refuse(f"{flag} {seconds:g} is not a positive "
|
|
88
|
+
"number of seconds")
|
|
89
|
+
if args.store is not None:
|
|
90
|
+
# P9, D16: one variable, set before the table is built and any
|
|
91
|
+
# child is spawned -- `paths.trace_root` reads it on every call
|
|
92
|
+
# and the children inherit it.
|
|
93
|
+
os.environ["SENSORIUM_DIR"] = str(Path(args.store).resolve())
|
|
94
|
+
try:
|
|
95
|
+
table = tools.table(args.allow_run)
|
|
96
|
+
except schema.SchemaError as blank:
|
|
97
|
+
return _refuse(str(blank))
|
|
98
|
+
return server.main(server.Options(
|
|
99
|
+
allow_run=args.allow_run, store=args.store,
|
|
100
|
+
max_output=args.max_output, timeout=args.timeout,
|
|
101
|
+
run_timeout=args.run_timeout), table)
|
sensorium/mcp/jsonrpc.py
ADDED
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
"""JSON-RPC 2.0 over stdio: one message per line, each way.
|
|
2
|
+
|
|
3
|
+
The whole transport, and nothing above it. `parse_line` turns a line of
|
|
4
|
+
stdin into an `Incoming` or into the three values an error response
|
|
5
|
+
needs; `Writer` puts one compact line on stdout under one lock. What a
|
|
6
|
+
method MEANS, which era it belongs to and whether it may run a program
|
|
7
|
+
are the server's questions -- this module knows only the envelope, and
|
|
8
|
+
that is why it can be tested without a process.
|
|
9
|
+
|
|
10
|
+
WHAT THE PARSER REFUSES, AND WHY EACH GETS ITS OWN CODE. A line that is
|
|
11
|
+
not JSON is `-32700`: nothing about it can be trusted, not even its id,
|
|
12
|
+
so the response carries `null`. A JSON ARRAY is `-32600` and says so in
|
|
13
|
+
words -- batching left the protocol in 2025-06-18, and a client that
|
|
14
|
+
sends a batch is not making a typo, it is speaking a revision this
|
|
15
|
+
server does not implement; answering `-32700` would send it looking for
|
|
16
|
+
a syntax error that is not there. An object with no string `method` is
|
|
17
|
+
`-32600` too, but it keeps its id: the client is blocked on that id and
|
|
18
|
+
a `null` there would leave it waiting forever. `params` that is present
|
|
19
|
+
and not an object is `-32602`, because the envelope was fine and the
|
|
20
|
+
payload was not; absent or `null` is `{}`, which is what every caller
|
|
21
|
+
in this codebase reads next.
|
|
22
|
+
|
|
23
|
+
A BLANK LINE IS NOT A MESSAGE. `parse_line` returns `None` for one and
|
|
24
|
+
the reader skips it. A trailing newline on a client's last write is not
|
|
25
|
+
a malformed request, and answering `-32700` to one would put a line on
|
|
26
|
+
stdout that no client is waiting for.
|
|
27
|
+
|
|
28
|
+
`None` IS ALSO "NOTHING TO ANSWER". A message with a string `method` and
|
|
29
|
+
no `id` KEY is a Notification, and JSON-RPC 2.0 §4.1 says a server must
|
|
30
|
+
not reply to one -- so a notification whose `params` is not an object is
|
|
31
|
+
refused by being dropped, not by a `-32602` carrying `id: null`. That is
|
|
32
|
+
the one place `obj.get("id")` could not tell "no id key" from
|
|
33
|
+
`"id": null`. An object with no string `method` is NOT a notification,
|
|
34
|
+
because it is not a Request at all, and it keeps its null-id answer:
|
|
35
|
+
that is the specification's own worked example.
|
|
36
|
+
|
|
37
|
+
IDS KEEP THEIR JSON TYPE (P21). `Incoming.id` is the parsed value --
|
|
38
|
+
`7` stays an int, `"7"` stays a string, and `Writer` echoes back what it
|
|
39
|
+
was handed. Normalising to `str` would let a `notifications/cancelled`
|
|
40
|
+
naming `"7"` cancel the call whose id is `7`, which is a different
|
|
41
|
+
request from a different client loop.
|
|
42
|
+
|
|
43
|
+
A WRITE IS NEVER A REASON TO DIE. When the client is gone, `write`
|
|
44
|
+
raises `BrokenPipeError`, and when our own stdout has been closed
|
|
45
|
+
underneath us it raises `ValueError("I/O operation on closed file")`.
|
|
46
|
+
Both set `closing` and are swallowed: by then there is nobody to tell,
|
|
47
|
+
and a server that raised out of its writer would abandon a live child
|
|
48
|
+
instead of running its shutdown. Everything else -- a result holding an
|
|
49
|
+
object `json` cannot serialise, say -- is OUR bug and is raised, so the
|
|
50
|
+
worker's `except` can answer `-32603` rather than lose the request.
|
|
51
|
+
`json.dumps` therefore runs outside the `try` and outside the lock, and
|
|
52
|
+
the `ValueError` clause asks the stream whether it is CLOSED: a
|
|
53
|
+
`ValueError` off a healthy stream is not a gone client and swallowing
|
|
54
|
+
it would lose the response it belongs to.
|
|
55
|
+
|
|
56
|
+
THE WIRE IS ASCII (`ensure_ascii=True`). Not aesthetics -- a text a
|
|
57
|
+
model can put in front of us may hold a LONE SURROGATE (a tokenizer
|
|
58
|
+
splitting an emoji is the usual cause), and a method name, a tool name
|
|
59
|
+
and a rejection message are all echoed back to the client. Written raw,
|
|
60
|
+
such a string cannot be encoded onto a UTF-8 stdout at all: the write
|
|
61
|
+
raised `UnicodeEncodeError` -- a `ValueError` -- the response was
|
|
62
|
+
dropped on a perfectly healthy pipe, and the client waited on that id
|
|
63
|
+
until its own timeout. Escaped, it is `\\ud800` on the wire and
|
|
64
|
+
`json.loads` hands the client back the same string. Legitimate
|
|
65
|
+
non-ASCII pays six characters per character for that; an answer that
|
|
66
|
+
arrives is worth more than an answer that is pretty.
|
|
67
|
+
"""
|
|
68
|
+
from __future__ import annotations
|
|
69
|
+
|
|
70
|
+
import json
|
|
71
|
+
import threading
|
|
72
|
+
from dataclasses import dataclass
|
|
73
|
+
|
|
74
|
+
#: The protocol's own numbers. `-32022` is 2026-07-28's
|
|
75
|
+
#: `UnsupportedProtocolVersionError`; the rest are JSON-RPC 2.0's.
|
|
76
|
+
PARSE_ERROR = -32700
|
|
77
|
+
INVALID_REQUEST = -32600
|
|
78
|
+
METHOD_NOT_FOUND = -32601
|
|
79
|
+
INVALID_PARAMS = -32602
|
|
80
|
+
INTERNAL_ERROR = -32603
|
|
81
|
+
UNSUPPORTED_VERSION = -32022
|
|
82
|
+
|
|
83
|
+
#: Said in full so a client reading the message learns the revision it
|
|
84
|
+
#: is out of step with, not merely that we said no.
|
|
85
|
+
_BATCHING = "Invalid Request: batching left the protocol in 2025-06-18"
|
|
86
|
+
_NO_METHOD = "Invalid Request: no method"
|
|
87
|
+
_BAD_PARAMS = "params must be an object"
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
@dataclass(frozen=True)
|
|
91
|
+
class Incoming:
|
|
92
|
+
"""One well-formed message. `notification` is `"id" not in obj` --
|
|
93
|
+
an explicit `"id": null` is a REQUEST whose id happens to be null,
|
|
94
|
+
and it gets an answer; a message with no id key at all gets none."""
|
|
95
|
+
|
|
96
|
+
id: object
|
|
97
|
+
method: str
|
|
98
|
+
params: dict
|
|
99
|
+
notification: bool
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def parse_line(line: str) -> Incoming | tuple[int, str, object] | None:
|
|
103
|
+
"""`Incoming`, or `(code, message, id)`, or `None` for nothing.
|
|
104
|
+
|
|
105
|
+
The tuple is exactly `Writer.error`'s first three arguments, so the
|
|
106
|
+
reader loop never has to decide anything: it writes what it got.
|
|
107
|
+
`None` is "there is nothing to answer" -- a blank line, or a
|
|
108
|
+
notification this parser refuses (§4.1).
|
|
109
|
+
"""
|
|
110
|
+
if not line.strip():
|
|
111
|
+
return None
|
|
112
|
+
try:
|
|
113
|
+
obj = json.loads(line)
|
|
114
|
+
except ValueError:
|
|
115
|
+
return PARSE_ERROR, "Parse error", None
|
|
116
|
+
if isinstance(obj, list):
|
|
117
|
+
return INVALID_REQUEST, _BATCHING, None
|
|
118
|
+
if not isinstance(obj, dict):
|
|
119
|
+
# A bare scalar: valid JSON, and no more a request than `[]` is.
|
|
120
|
+
return INVALID_REQUEST, _NO_METHOD, None
|
|
121
|
+
method = obj.get("method")
|
|
122
|
+
if not isinstance(method, str):
|
|
123
|
+
return INVALID_REQUEST, _NO_METHOD, obj.get("id")
|
|
124
|
+
params = obj.get("params")
|
|
125
|
+
if params is None:
|
|
126
|
+
params = {}
|
|
127
|
+
elif not isinstance(params, dict):
|
|
128
|
+
if "id" not in obj:
|
|
129
|
+
return None # a NOTIFICATION: §4.1, no reply, not even this
|
|
130
|
+
return INVALID_PARAMS, _BAD_PARAMS, obj["id"]
|
|
131
|
+
return Incoming(obj.get("id"), method, params, "id" not in obj)
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
class Writer:
|
|
135
|
+
"""Stdout, one JSON-RPC message per line, from any thread.
|
|
136
|
+
|
|
137
|
+
The lock is not decoration: the reader thread answers `ping` and
|
|
138
|
+
parse errors while the worker thread answers everything else, and
|
|
139
|
+
two interleaved halves of two messages are two lines no client can
|
|
140
|
+
parse. It covers the flush as well as the write -- a flush between
|
|
141
|
+
somebody else's write and its own would ship a half line.
|
|
142
|
+
"""
|
|
143
|
+
|
|
144
|
+
def __init__(self, stream) -> None:
|
|
145
|
+
self._stream = stream
|
|
146
|
+
self._lock = threading.Lock()
|
|
147
|
+
self.closing = False
|
|
148
|
+
|
|
149
|
+
def result(self, id: object, result: dict) -> None:
|
|
150
|
+
self._write({"jsonrpc": "2.0", "id": id, "result": result})
|
|
151
|
+
|
|
152
|
+
def error(self, id: object, code: int, message: str,
|
|
153
|
+
data: object = None) -> None:
|
|
154
|
+
err: dict = {"code": code, "message": message}
|
|
155
|
+
if data is not None:
|
|
156
|
+
err["data"] = data
|
|
157
|
+
self._write({"jsonrpc": "2.0", "id": id, "error": err})
|
|
158
|
+
|
|
159
|
+
def _write(self, obj: dict) -> None:
|
|
160
|
+
line = json.dumps(obj, separators=(",", ":")) + "\n"
|
|
161
|
+
with self._lock:
|
|
162
|
+
try:
|
|
163
|
+
self._stream.write(line)
|
|
164
|
+
self._stream.flush()
|
|
165
|
+
except BrokenPipeError:
|
|
166
|
+
self.closing = True
|
|
167
|
+
except ValueError:
|
|
168
|
+
# ONLY the closed-file one. Anything else off an open
|
|
169
|
+
# stream is our bug and belongs to the worker's -32603.
|
|
170
|
+
if not getattr(self._stream, "closed", False):
|
|
171
|
+
raise
|
|
172
|
+
self.closing = True
|
sensorium/mcp/result.py
ADDED
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
"""An `Outcome` as the model reads it: a header, the streams, a cap.
|
|
2
|
+
|
|
3
|
+
THE HEADER IS THE FIRST LINE, ALWAYS (D19). A model branches on it
|
|
4
|
+
before it reads a word of prose, exactly as the debugging skills teach
|
|
5
|
+
it to branch on `$?`, so the words are `exit.MEANING`'s and not a second
|
|
6
|
+
copy of them (P3): a status whose sentence is reworded takes its header
|
|
7
|
+
with it, and a status that MOVED takes its sentence. It is also the
|
|
8
|
+
exit's only machine-readable carrier (R18): nothing here writes
|
|
9
|
+
`structuredContent`, because the deploy target E17 measured shows a
|
|
10
|
+
model that key INSTEAD of the text.
|
|
11
|
+
|
|
12
|
+
Two statuses are not the four-way contract and say so. `record` is the
|
|
13
|
+
CLI's `run`, whose exit is the recorded command's own -- an `exit 2`
|
|
14
|
+
there means the target exited 2, or that recording was refused and there
|
|
15
|
+
is no trace, never "the call is wrong". A child killed by a signal has
|
|
16
|
+
no status at all, only the signal, and reads the same on every tool.
|
|
17
|
+
A call that produced no exit (a timeout, a cancel, a spawn that never
|
|
18
|
+
happened) reads `no answer:` and the cause, because there is no number
|
|
19
|
+
to report and inventing one would be a lie a model acts on.
|
|
20
|
+
|
|
21
|
+
STDERR IS ALWAYS LABELLED (P4, amending D20). The spec labelled it only
|
|
22
|
+
when stdout was non-empty; two corpus refusals print to stderr alone,
|
|
23
|
+
and an unlabelled body cannot be attributed to a stream by a client that
|
|
24
|
+
must split the text back into `(stdout, stderr, exit)`. The label is a
|
|
25
|
+
line of its own, which costs one thing and one only: a stdout that
|
|
26
|
+
lacked its trailing newline gains one before the label, so a client
|
|
27
|
+
cannot reassemble THAT case byte-exactly. It is documented in `text_of`
|
|
28
|
+
and it is the whole of the loss.
|
|
29
|
+
|
|
30
|
+
THE CAP KEEPS A HEAD AND A TAIL (D24), not a head. `diff` and `refocus`
|
|
31
|
+
print their verdict and their drill-in commands LAST; a model handed
|
|
32
|
+
only the head of a DIVERGED answer has the exit and not the fork. Both
|
|
33
|
+
ends are cut back to a line boundary when the kept window holds a
|
|
34
|
+
newline; a window without one is a raw byte cut and may begin or end in
|
|
35
|
+
U+FFFD (the invariant can then be exceeded by the width of one replaced
|
|
36
|
+
character at each cut). The marker names the fields this tool narrows
|
|
37
|
+
by -- the cut is ours and named, the reason `--max-output` sits under
|
|
38
|
+
the client's own silent cap at all (D23).
|
|
39
|
+
|
|
40
|
+
This module renders. `audit.py` records; the two never import each
|
|
41
|
+
other, and the server is what calls both.
|
|
42
|
+
"""
|
|
43
|
+
from __future__ import annotations
|
|
44
|
+
|
|
45
|
+
import signal
|
|
46
|
+
|
|
47
|
+
from sensorium import exit as ex
|
|
48
|
+
from sensorium.mcp.child import Outcome
|
|
49
|
+
from sensorium.mcp.schema import Rejection
|
|
50
|
+
from sensorium.mcp.tools import Tool, narrowing_fields
|
|
51
|
+
|
|
52
|
+
#: The line that separates stdout from stderr. A line of its own, so a
|
|
53
|
+
#: client can split on it (P4); the corpus client does exactly that.
|
|
54
|
+
STDERR_LABEL = "--- stderr ---"
|
|
55
|
+
|
|
56
|
+
#: The bytes kept from the END of an over-long body, when the limit is
|
|
57
|
+
#: big enough to spare them (D24).
|
|
58
|
+
KEEP_TAIL = 4096
|
|
59
|
+
|
|
60
|
+
#: `record`'s header tail: `run`'s exit is the target's own.
|
|
61
|
+
_RECORDED = ("the recorded command's own status (2 and no trace when "
|
|
62
|
+
"recording was refused)")
|
|
63
|
+
|
|
64
|
+
#: ...and the tail for an exit that is neither the contract's nor a
|
|
65
|
+
#: signal's. Never expected; named rather than rendered as an answer.
|
|
66
|
+
_OFF_CONTRACT = "an exit outside the query contract"
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _signal_name(n: int) -> str:
|
|
70
|
+
"""`SIGTERM` for a signal CPython names, `signal 35` for one it does
|
|
71
|
+
not: `Signals` covers 1-34 and 64 only while Linux's `WTERMSIG`
|
|
72
|
+
reaches 64, so `SIGRTMIN+1` would raise out of `header` (R11)."""
|
|
73
|
+
try:
|
|
74
|
+
return signal.Signals(n).name
|
|
75
|
+
except ValueError:
|
|
76
|
+
return f"signal {n}"
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def header(tool: Tool, o: Outcome) -> str:
|
|
80
|
+
"""The first line of every result: what happened, in one sentence."""
|
|
81
|
+
if o.exit is None:
|
|
82
|
+
return f"no answer: {o.cause or 'unknown'}"
|
|
83
|
+
if o.exit < 0:
|
|
84
|
+
return f"exit {o.exit}: killed by {_signal_name(-o.exit)}"
|
|
85
|
+
if tool.schema.command == "run": # the tool `record`
|
|
86
|
+
return f"exit {o.exit}: {_RECORDED}"
|
|
87
|
+
return f"exit {o.exit}: {ex.MEANING.get(o.exit, _OFF_CONTRACT)}"
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def text_of(tool: Tool, o: Outcome) -> str:
|
|
91
|
+
"""`header`, then stdout, then stderr under `STDERR_LABEL`.
|
|
92
|
+
|
|
93
|
+
Nothing is appended that the streams did not carry, with one
|
|
94
|
+
exception: a non-empty stderr whose preceding text does not end in a
|
|
95
|
+
newline gets one, so the label always starts a line. That is the
|
|
96
|
+
single case a client cannot split back byte-exactly -- it recovers
|
|
97
|
+
the streams, not the missing final newline of a ragged stdout.
|
|
98
|
+
"""
|
|
99
|
+
text = header(tool, o) + "\n" + o.stdout
|
|
100
|
+
if o.stderr:
|
|
101
|
+
if not text.endswith("\n"):
|
|
102
|
+
text += "\n"
|
|
103
|
+
text += STDERR_LABEL + "\n" + o.stderr
|
|
104
|
+
return text
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def cap(text: str, limit: int, narrowing: tuple[str, ...]
|
|
108
|
+
) -> tuple[str, bool, int, int]:
|
|
109
|
+
"""`(text, truncated, omitted_lines, omitted_bytes)`, head and tail.
|
|
110
|
+
|
|
111
|
+
The header line is never cut: the cap applies to everything after
|
|
112
|
+
the first newline, so a limit smaller than the header still leaves a
|
|
113
|
+
result a model can branch on. Both kept halves are cut back to a line
|
|
114
|
+
boundary when the kept window holds a newline -- the head back to its
|
|
115
|
+
last, the tail forward past its first; a window without one is a raw
|
|
116
|
+
byte cut and may begin or end in U+FFFD (the invariant can then be
|
|
117
|
+
exceeded by the width of one replaced character at each cut). The
|
|
118
|
+
marker line is not counted against the limit: it is the cap's own
|
|
119
|
+
sentence, not the child's output.
|
|
120
|
+
"""
|
|
121
|
+
nl = text.find("\n")
|
|
122
|
+
head_line, body = (text, "") if nl < 0 else (text[:nl], text[nl + 1:])
|
|
123
|
+
raw = body.encode("utf-8")
|
|
124
|
+
if len(raw) <= limit:
|
|
125
|
+
return text, False, 0, 0
|
|
126
|
+
# max(1, ...): under limit 4, `limit // 4` is 0, `raw[-0:]` the WHOLE
|
|
127
|
+
# buffer -- a "cap" emitting everything it claimed to cut.
|
|
128
|
+
keep_tail = max(1, min(KEEP_TAIL, limit // 4))
|
|
129
|
+
# max(0, ...): at limit 0 the floor above makes `limit - keep_tail`
|
|
130
|
+
# -1, and `raw[:-1]` is all but one byte of the body the marker has
|
|
131
|
+
# just declared omitted -- the same inversion one step further down.
|
|
132
|
+
keep_head = max(0, limit - keep_tail)
|
|
133
|
+
head = raw[:keep_head]
|
|
134
|
+
head = head[:head.rfind(b"\n") + 1] if b"\n" in head else head
|
|
135
|
+
tail = raw[-keep_tail:]
|
|
136
|
+
tail = tail[tail.find(b"\n") + 1:] if b"\n" in tail else tail
|
|
137
|
+
omitted = raw[len(head):len(raw) - len(tail)]
|
|
138
|
+
lines = omitted.count(b"\n")
|
|
139
|
+
narrow = ", ".join(narrowing) if narrowing else "nothing on this tool"
|
|
140
|
+
marker = (f"[... {lines:,} lines ({len(omitted):,} bytes) omitted; "
|
|
141
|
+
f"narrow with: {narrow} ...]\n")
|
|
142
|
+
out = head.decode("utf-8", "replace") + marker + tail.decode("utf-8",
|
|
143
|
+
"replace")
|
|
144
|
+
return head_line + "\n" + out, True, lines, len(omitted)
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
def call_result(tool: Tool, o: Outcome, limit: int,
|
|
148
|
+
modern: bool) -> tuple[dict, bool]:
|
|
149
|
+
"""The `tools/call` result for one outcome, and whether it was cut.
|
|
150
|
+
|
|
151
|
+
`isError` is true exactly when the exit is 2 or there is no exit
|
|
152
|
+
(D22): 2 is the call the model should repair itself, which is what
|
|
153
|
+
the protocol says the flag is for, while 1 and 3 are answers ABOUT
|
|
154
|
+
the trace and a signal is a death, not a misuse. The key is omitted
|
|
155
|
+
rather than sent false -- absent is the protocol's default.
|
|
156
|
+
|
|
157
|
+
`_meta` is never added here (R1): the server owns the serverInfo it
|
|
158
|
+
stamps on every modern result, and two hands writing one key is how
|
|
159
|
+
they disagree.
|
|
160
|
+
"""
|
|
161
|
+
text, truncated, _lines, _nbytes = cap(text_of(tool, o), limit,
|
|
162
|
+
narrowing_fields(tool))
|
|
163
|
+
out: dict = {"content": [{"type": "text", "text": text}]}
|
|
164
|
+
if o.exit == 2 or o.exit is None:
|
|
165
|
+
out["isError"] = True
|
|
166
|
+
if modern:
|
|
167
|
+
out["resultType"] = "complete"
|
|
168
|
+
return out, truncated
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
def rejection_result(r: Rejection, modern: bool) -> dict:
|
|
172
|
+
"""A refused call, as a RESULT rather than a protocol error (P30).
|
|
173
|
+
|
|
174
|
+
Both revisions reserve `-32602` for unknown tools and malformed
|
|
175
|
+
requests and route argument-validation failures through `isError`,
|
|
176
|
+
which is the channel the model sees and repairs from -- naming the
|
|
177
|
+
fields in an error the client swallows would defeat the point of
|
|
178
|
+
naming them. So it is an ordinary exit-2 answer, in the same words
|
|
179
|
+
an exit 2 from the CLI would have used, with the rejection's own
|
|
180
|
+
message under it.
|
|
181
|
+
"""
|
|
182
|
+
text = f"exit {ex.BAD_CALL}: {ex.MEANING[ex.BAD_CALL]}\n{r.message}"
|
|
183
|
+
out: dict = {"content": [{"type": "text", "text": text}]}
|
|
184
|
+
out["isError"] = True
|
|
185
|
+
if modern:
|
|
186
|
+
out["resultType"] = "complete"
|
|
187
|
+
return out
|