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.
Files changed (135) hide show
  1. sensorium/__init__.py +0 -0
  2. sensorium/__main__.py +4 -0
  3. sensorium/_c/rt/sensorium_c_rt.c +1446 -0
  4. sensorium/_typescript/package-lock.json +68 -0
  5. sensorium/_typescript/package.json +39 -0
  6. sensorium/_typescript/src/bindings.mjs +792 -0
  7. sensorium/_typescript/src/cap.mjs +227 -0
  8. sensorium/_typescript/src/capabilities.mjs +40 -0
  9. sensorium/_typescript/src/dbg.mjs +348 -0
  10. sensorium/_typescript/src/escape.mjs +351 -0
  11. sensorium/_typescript/src/focus.mjs +135 -0
  12. sensorium/_typescript/src/hook.mjs +127 -0
  13. sensorium/_typescript/src/index.mjs +1 -0
  14. sensorium/_typescript/src/naming.mjs +63 -0
  15. sensorium/_typescript/src/positions.mjs +37 -0
  16. sensorium/_typescript/src/probe.mjs +246 -0
  17. sensorium/_typescript/src/qualname.mjs +236 -0
  18. sensorium/_typescript/src/redact.mjs +711 -0
  19. sensorium/_typescript/src/register.mjs +15 -0
  20. sensorium/_typescript/src/resolve.mjs +260 -0
  21. sensorium/_typescript/src/rt.mjs +798 -0
  22. sensorium/_typescript/src/setup.mjs +11 -0
  23. sensorium/_typescript/src/tally.mjs +164 -0
  24. sensorium/_typescript/src/tasks.mjs +175 -0
  25. sensorium/_typescript/src/transform.mjs +800 -0
  26. sensorium/_typescript/src/vite.mjs +99 -0
  27. sensorium/c/__init__.py +8 -0
  28. sensorium/c/cc.py +612 -0
  29. sensorium/c/cli.py +60 -0
  30. sensorium/c/convert.py +669 -0
  31. sensorium/c/decode.py +300 -0
  32. sensorium/c/driver.py +365 -0
  33. sensorium/c/dwarf.py +706 -0
  34. sensorium/c/format.py +271 -0
  35. sensorium/c/pkg.py +187 -0
  36. sensorium/c/plan.py +277 -0
  37. sensorium/cli.py +140 -0
  38. sensorium/driver.py +47 -0
  39. sensorium/exit.py +33 -0
  40. sensorium/invocations.py +83 -0
  41. sensorium/limits.py +253 -0
  42. sensorium/mcp/__init__.py +0 -0
  43. sensorium/mcp/audit.py +162 -0
  44. sensorium/mcp/child.py +240 -0
  45. sensorium/mcp/cmd.py +101 -0
  46. sensorium/mcp/jsonrpc.py +172 -0
  47. sensorium/mcp/result.py +187 -0
  48. sensorium/mcp/schema.py +390 -0
  49. sensorium/mcp/server.py +493 -0
  50. sensorium/mcp/tools.py +299 -0
  51. sensorium/paths.py +80 -0
  52. sensorium/query/__init__.py +0 -0
  53. sensorium/query/caps.py +150 -0
  54. sensorium/query/dbg_dialects.py +64 -0
  55. sensorium/query/diff_cmd.py +748 -0
  56. sensorium/query/diff_notes.py +117 -0
  57. sensorium/query/exceptions_c.py +263 -0
  58. sensorium/query/exceptions_cmd.py +788 -0
  59. sensorium/query/exceptions_group.py +571 -0
  60. sensorium/query/exceptions_invocation.py +487 -0
  61. sensorium/query/exceptions_rust.py +683 -0
  62. sensorium/query/exceptions_typescript.py +688 -0
  63. sensorium/query/expr.py +606 -0
  64. sensorium/query/failures_cmd.py +306 -0
  65. sensorium/query/flow_cmd.py +778 -0
  66. sensorium/query/flow_report.py +128 -0
  67. sensorium/query/flow_values.py +195 -0
  68. sensorium/query/fmt.py +280 -0
  69. sensorium/query/frame_cmd.py +237 -0
  70. sensorium/query/grep_cmd.py +156 -0
  71. sensorium/query/help.py +18 -0
  72. sensorium/query/info_cmd.py +527 -0
  73. sensorium/query/info_rust.py +214 -0
  74. sensorium/query/info_typescript.py +261 -0
  75. sensorium/query/js_inspect.py +394 -0
  76. sensorium/query/moves.py +254 -0
  77. sensorium/query/redact_cmd.py +304 -0
  78. sensorium/query/refocus_cmd.py +661 -0
  79. sensorium/query/refocus_env.py +493 -0
  80. sensorium/query/refocus_facts.py +269 -0
  81. sensorium/query/refocus_licence.py +187 -0
  82. sensorium/query/refocus_report.py +327 -0
  83. sensorium/query/refocus_rust.py +537 -0
  84. sensorium/query/refocus_threads.py +197 -0
  85. sensorium/query/refocus_typescript.py +756 -0
  86. sensorium/query/refocus_world.py +666 -0
  87. sensorium/query/runs_cmd.py +213 -0
  88. sensorium/query/rust_debug.py +176 -0
  89. sensorium/query/sites.py +171 -0
  90. sensorium/query/tree_cmd.py +511 -0
  91. sensorium/query/tree_threads.py +168 -0
  92. sensorium/query/vocab.py +723 -0
  93. sensorium/query/watch_cmd.py +657 -0
  94. sensorium/record/__init__.py +0 -0
  95. sensorium/record/boot.py +797 -0
  96. sensorium/record/boot_io.py +141 -0
  97. sensorium/record/budget.py +135 -0
  98. sensorium/record/capture.py +433 -0
  99. sensorium/record/children.py +755 -0
  100. sensorium/record/children_merge.py +179 -0
  101. sensorium/record/elide.py +55 -0
  102. sensorium/record/fingerprint.py +26 -0
  103. sensorium/record/thread_starts.py +261 -0
  104. sensorium/record/tracer.py +798 -0
  105. sensorium/record/tracer_exc.py +199 -0
  106. sensorium/record/tracer_frames.py +618 -0
  107. sensorium/redact.py +304 -0
  108. sensorium/redact_content.py +156 -0
  109. sensorium/redact_key.py +317 -0
  110. sensorium/redact_store.py +502 -0
  111. sensorium/redact_values.py +433 -0
  112. sensorium/store/__init__.py +0 -0
  113. sensorium/store/db.py +284 -0
  114. sensorium/store/gc.py +360 -0
  115. sensorium/store/payloads.py +69 -0
  116. sensorium/store/reader.py +438 -0
  117. sensorium/store/writer.py +283 -0
  118. sensorium/ts/__init__.py +10 -0
  119. sensorium/ts/build.py +783 -0
  120. sensorium/ts/cli.py +130 -0
  121. sensorium/ts/driver.py +472 -0
  122. sensorium/ts/focus.py +146 -0
  123. sensorium/ts/harness.py +314 -0
  124. sensorium/ts/ingest.py +380 -0
  125. sensorium/ts/invocation.py +252 -0
  126. sensorium/ts/pkg.py +167 -0
  127. sensorium/ts/redaction.py +64 -0
  128. sensorium/ts/spool.py +168 -0
  129. sensorium/ts/truncation.py +81 -0
  130. sensorium/ts/wrapper.py +255 -0
  131. sensorium_trace-0.18.2.dist-info/METADATA +245 -0
  132. sensorium_trace-0.18.2.dist-info/RECORD +135 -0
  133. sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
  134. sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
  135. 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)
@@ -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
@@ -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