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
@@ -0,0 +1,390 @@
1
+ """A tool's fields, derived from the query command's own argparse parser.
2
+
3
+ The CLI already says what every query command takes, in the one place
4
+ that cannot drift from what the command does: its `add_parser`. This
5
+ module reads that parser and answers what an MCP server asks of it --
6
+ what fields a tool has (`derive`), how a client is shown them
7
+ (`json_schema`), and what argv a call becomes (`to_argv`, and
8
+ `from_argv` back again). A hand-written second table would be right on
9
+ the day it was written and wrong the first time an `add_argument`
10
+ changed, and the error it produces is the worst kind: a tool table
11
+ describing a CLI nobody has.
12
+
13
+ WHAT THE PARSER SAYS, AND WHAT THIS MAKES OF IT
14
+ -----------------------------------------------
15
+ | the action | the field |
16
+ |-----------------------------|------------------------------------|
17
+ | `argparse._HelpAction` | skipped -- `-h` is not a field |
18
+ | `dest` | the field's name |
19
+ | `_StoreTrueAction` | boolean |
20
+ | `_AppendAction` | array of string |
21
+ | `choices=` | enum of those choices |
22
+ | `type=int` | integer |
23
+ | anything else | string |
24
+ | positional, `nargs=None` | required |
25
+ | positional, `nargs="?"` | optional |
26
+ | `action.required` (P2) | required; an array also `minItems` |
27
+ | positional named `run` (D5) | optional, default `last` |
28
+ | `help=argparse.SUPPRESS` | no field at all |
29
+ | `help=` empty or None | `SchemaError`: refuse to boot |
30
+ | a default not None/[]/False | the field's `"default"` |
31
+
32
+ P2 is what a positional-only reading misses: `watch --at`, `watch
33
+ --expr` and `refocus --focus` are required OPTIONS, and a model that
34
+ omitted one because the schema called it optional would meet argparse's
35
+ exit 2 for a field it was told it could leave out.
36
+
37
+ D6 is the opposite case. `flow --value` and `--object` sit in a mutually
38
+ exclusive group with `required=True`, which means EXACTLY ONE -- a rule
39
+ no JSON Schema `required` list can state. `required` is read from the
40
+ ACTION alone, never from the group, so both are optional here and `flow`
41
+ itself refuses by name when neither is given.
42
+
43
+ D5 is `run`. Every query command takes one and `last` is what a caller
44
+ almost always means, so a default here spares it a `runs` call before
45
+ every question. It lives in the schema and in `to_argv` and never in the
46
+ parser: the CLI's own `run` positional is still required.
47
+
48
+ `json_schema` sets `"additionalProperties": false` so a client that
49
+ validates locally refuses exactly what `to_argv` refuses -- a field this
50
+ tool does not have is worth catching before the call, not after.
51
+
52
+ `from_argv` is the inverse (P25): argv WITHOUT the command word becomes
53
+ `{dest: value}`, dropping `None`, `[]`, `False` and any value equal to
54
+ the parser's own default, which argparse cannot tell from a defaulted
55
+ one. `tests/test_mcp_schema.py` pins the round trip over every corpus
56
+ question, compared as parses.
57
+ """
58
+ from __future__ import annotations
59
+
60
+ import argparse
61
+ import contextlib
62
+ import io
63
+ from dataclasses import dataclass, field as _dataclass_field
64
+
65
+ #: D5: what `run` means when a call leaves it out.
66
+ RUN_DEFAULT = "last"
67
+
68
+ #: The JSON type each field kind is shown as. An enum is a string with a
69
+ #: closed set; an array's items are strings throughout this CLI.
70
+ _JSON_TYPE = {"string": "string", "integer": "integer",
71
+ "boolean": "boolean", "array": "array", "enum": "string"}
72
+
73
+ #: ...and what a refusal calls it when the value is of the wrong one.
74
+ _EXPECTED = {"string": "string", "integer": "integer",
75
+ "boolean": "boolean", "array": "array of string"}
76
+
77
+
78
+ class SchemaError(Exception):
79
+ """A parser this server cannot describe: raised while deriving,
80
+ never while answering. The server refuses to boot rather than ship a
81
+ tool whose field says nothing."""
82
+
83
+
84
+ class Rejection(Exception):
85
+ """A call that will not be made, and the reason a caller can act on."""
86
+
87
+ def __init__(self, reason: str, fields, message: str) -> None:
88
+ super().__init__(message)
89
+ #: "unknown_fields" | "bad_fields" | "missing_fields"
90
+ self.reason = reason
91
+ #: The offending field names, all of them, in schema order.
92
+ self.fields = tuple(fields)
93
+ self.message = message
94
+
95
+
96
+ @dataclass(frozen=True)
97
+ class Field:
98
+ name: str
99
+ kind: str # string|integer|boolean|array|enum
100
+ required: bool
101
+ description: str
102
+ default: object = None
103
+ enum: tuple[str, ...] = ()
104
+ positional: bool = False
105
+ option: str | None = None # "--kind"
106
+
107
+
108
+ @dataclass(frozen=True)
109
+ class ToolSchema:
110
+ command: str # the argv word: "grep"
111
+ fields: tuple[Field, ...] # positionals in parser order, then options
112
+ help: str # add_parser's help=
113
+ description: str # ...and its description=
114
+ #: The parser the fields were read off, so `from_argv` parses by the
115
+ #: very rules the CLI applies. Reached through `parser_for`, and out
116
+ #: of `==`: two schemas are equal when they say the same thing.
117
+ parser: argparse.ArgumentParser = _dataclass_field(repr=False,
118
+ compare=False)
119
+
120
+
121
+ # -- derivation -------------------------------------------------------------
122
+ def derive(module) -> ToolSchema:
123
+ """The tool schema for a query module -- anything with `add_parser`.
124
+
125
+ The parser is built here rather than taken from `cli.main`'s:
126
+ deriving must not depend on a live CLI."""
127
+ parser = argparse.ArgumentParser(prog="sensorium", exit_on_error=False)
128
+ sub = parser.add_subparsers(dest="cmd")
129
+ module.add_parser(sub)
130
+ (command, subparser), = sub.choices.items()
131
+ description = subparser.description or ""
132
+ if not description:
133
+ raise SchemaError(f"{command}: the command has no description; "
134
+ "the server refuses to boot")
135
+ positionals, options = [], []
136
+ for action in subparser._actions:
137
+ if isinstance(action, argparse._HelpAction):
138
+ continue
139
+ if action.help is argparse.SUPPRESS:
140
+ continue
141
+ if not action.help:
142
+ raise SchemaError(f"{command}: field {action.dest!r} has no "
143
+ "help; the server refuses to boot")
144
+ field = _field(action)
145
+ (positionals if field.positional else options).append(field)
146
+ return ToolSchema(command, tuple(positionals + options),
147
+ _command_help(sub, command), description, subparser)
148
+
149
+
150
+ def parser_for(ts: ToolSchema) -> argparse.ArgumentParser:
151
+ """The subparser `derive` read, for `from_argv` and for tests."""
152
+ return ts.parser
153
+
154
+
155
+ def _command_help(sub, command: str) -> str:
156
+ """`add_parser`'s `help=`, which argparse keeps on the pseudo-action
157
+ it made for the choice rather than on the subparser itself."""
158
+ for choice in sub._choices_actions:
159
+ if choice.dest == command and choice.help:
160
+ return choice.help
161
+ raise SchemaError(f"{command}: the command has no help; the server "
162
+ "refuses to boot")
163
+
164
+
165
+ def _field(action) -> Field:
166
+ positional = not action.option_strings
167
+ default = action.default
168
+ if default is None or default == [] or default is False:
169
+ default = None
170
+ if positional:
171
+ required = action.nargs is None
172
+ else:
173
+ required = bool(action.required) # P2
174
+ if positional and action.dest == "run": # D5
175
+ required, default = False, RUN_DEFAULT
176
+ # MCP's default, not the CLI's. `--compact` is store_true, so a
177
+ # person who types the command gets the long report the CLI tests
178
+ # snapshot. A tool caller gets the short one unless it passes false.
179
+ # The flag is applied in `tools.command_argv`, not in `to_argv`:
180
+ # `to_argv` rebuilds corpus questions that never passed the flag,
181
+ # and inventing it there would make those parses disagree.
182
+ if (not positional and action.dest == "compact"
183
+ and action.option_strings == ["--compact"]
184
+ and isinstance(action, argparse._StoreTrueAction)):
185
+ default = True
186
+ return Field(name=action.dest, kind=_kind(action), required=required,
187
+ description=action.help, default=default,
188
+ enum=tuple(action.choices) if action.choices else (),
189
+ positional=positional,
190
+ option=None if positional else action.option_strings[0])
191
+
192
+
193
+ def _kind(action) -> str:
194
+ if isinstance(action, argparse._StoreTrueAction):
195
+ return "boolean"
196
+ if isinstance(action, argparse._AppendAction):
197
+ return "array"
198
+ if action.choices:
199
+ return "enum"
200
+ if action.type is int:
201
+ return "integer"
202
+ return "string"
203
+
204
+
205
+ # -- what a client is shown -------------------------------------------------
206
+ def json_schema(ts: ToolSchema) -> dict:
207
+ return {
208
+ "type": "object",
209
+ "properties": {f.name: _property(f) for f in ts.fields},
210
+ "required": [f.name for f in ts.fields if f.required],
211
+ "additionalProperties": False,
212
+ }
213
+
214
+
215
+ def _property(f: Field) -> dict:
216
+ prop: dict = {"type": _JSON_TYPE[f.kind]}
217
+ if f.kind == "enum":
218
+ prop["enum"] = list(f.enum)
219
+ if f.kind == "array":
220
+ prop["items"] = {"type": "string"}
221
+ if f.required:
222
+ prop["minItems"] = 1
223
+ prop["description"] = f.description
224
+ if f.default is not None:
225
+ prop["default"] = f.default
226
+ return prop
227
+
228
+
229
+ # -- a call becomes argv ----------------------------------------------------
230
+ def validate(ts: ToolSchema, arguments: dict) -> None:
231
+ """Raise the `Rejection` this call has earned, or return.
232
+
233
+ Whole and in this order: a caller told of one bad field at a time
234
+ needs one round trip per mistake, and a missing field reported ahead
235
+ of a misspelt one sends the retry after the wrong thing. Public
236
+ because `record` (`mcp.tools`) is refused by these rules and then
237
+ builds argv of its own -- `run --focus … -- <command>` is not the
238
+ shape `to_argv` makes -- and two copies of a refusal drift.
239
+ """
240
+ by_name = {f.name: f for f in ts.fields}
241
+ _reject_unknown(ts, arguments, by_name)
242
+ _reject_bad_values(ts, arguments, by_name)
243
+ _reject_missing(ts, arguments)
244
+
245
+
246
+ def to_argv(ts: ToolSchema, arguments: dict) -> list[str]:
247
+ """`[command, *options, "--", *positionals]` for a validated call.
248
+
249
+ THE SHAPE IS THE ESCAPE A TOOL CALLER DOES NOT HAVE. Emitted as two
250
+ words (`["--fn", value]`) with the positionals bare, ANY value
251
+ beginning with `-` was read by the child's argparse as an option:
252
+ `grep {"pattern": "-x"}` came back *the following arguments are
253
+ required: pattern*, naming the one field the model HAD supplied.
254
+ A shell user types `sensorium grep last -- -x`; a model has no
255
+ field and no spelling to reach for, and `-1` happened to work
256
+ (argparse matches negative numbers), which made the dead end look
257
+ arbitrary rather than structural.
258
+
259
+ So: `--name=value`, which cannot be mistaken for a flag-plus-value,
260
+ and one `--` before the positional block, which ends option parsing
261
+ for good. The `--` is omitted when there are no positionals (`runs`
262
+ has no fields at all) rather than emitted as a word with nothing
263
+ after it. `record`'s argv is `tools.command_argv`'s, not this one:
264
+ its `--` separates the TARGET's argv and means something else.
265
+ """
266
+ validate(ts, arguments)
267
+ options: list[str] = []
268
+ for f in ts.fields:
269
+ if f.positional or f.name not in arguments:
270
+ continue
271
+ value = arguments[f.name]
272
+ if f.kind == "boolean":
273
+ if value:
274
+ options.append(f.option)
275
+ elif f.kind == "array":
276
+ options.extend(f"{f.option}={item}" for item in value)
277
+ else:
278
+ options.append(f"{f.option}={_word(f, value)}")
279
+ positionals: list[str] = []
280
+ for f in ts.fields:
281
+ if not f.positional:
282
+ continue
283
+ if f.name in arguments:
284
+ positionals.append(_word(f, arguments[f.name]))
285
+ elif f.default is not None:
286
+ positionals.append(str(f.default)) # D5
287
+ if not positionals:
288
+ return [ts.command, *options]
289
+ return [ts.command, *options, "--", *positionals]
290
+
291
+
292
+ def _word(f: Field, value) -> str:
293
+ return str(value) if f.kind == "integer" else value
294
+
295
+
296
+ def _reject_unknown(ts: ToolSchema, arguments: dict, by_name: dict) -> None:
297
+ unknown = [name for name in arguments if name not in by_name]
298
+ if not unknown:
299
+ return
300
+ raise Rejection(
301
+ "unknown_fields", unknown,
302
+ f"unknown field{'s' if len(unknown) > 1 else ''} "
303
+ f"{', '.join(repr(n) for n in unknown)} for {ts.command}; fields: "
304
+ f"{', '.join(f.name for f in ts.fields)}")
305
+
306
+
307
+ def _reject_bad_values(ts: ToolSchema, arguments: dict,
308
+ by_name: dict) -> None:
309
+ bad, clauses = [], []
310
+ for name, value in arguments.items():
311
+ f = by_name[name]
312
+ if _well_typed(f, value):
313
+ continue
314
+ bad.append(name)
315
+ expected = ("one of " + ", ".join(f.enum) if f.kind == "enum"
316
+ else _EXPECTED[f.kind])
317
+ clauses.append(f"bad value for {name!r} on {ts.command}: "
318
+ f"expected {expected}")
319
+ if bad:
320
+ raise Rejection("bad_fields", bad, "; ".join(clauses))
321
+
322
+
323
+ def _well_typed(f: Field, value) -> bool:
324
+ # `type(value) is bool` before the integer check, always: Python's
325
+ # `bool` IS an `int`, so `isinstance(True, int)` would accept `true`
326
+ # for `--limit` and hand argparse the word "True".
327
+ if f.kind == "boolean":
328
+ return type(value) is bool
329
+ if f.kind == "integer":
330
+ return type(value) is not bool and isinstance(value, int)
331
+ if f.kind == "array":
332
+ return (isinstance(value, list)
333
+ and all(isinstance(item, str) for item in value))
334
+ if f.kind == "enum":
335
+ return isinstance(value, str) and value in f.enum
336
+ return isinstance(value, str)
337
+
338
+
339
+ def _reject_missing(ts: ToolSchema, arguments: dict) -> None:
340
+ missing = [f.name for f in ts.fields
341
+ if f.required and _absent(f, arguments)]
342
+ if missing:
343
+ raise Rejection("missing_fields", missing,
344
+ f"missing required field(s) for {ts.command}: "
345
+ f"{', '.join(missing)}")
346
+
347
+
348
+ def _absent(f: Field, arguments: dict) -> bool:
349
+ """...and `--focus: []` is absent too, not an empty one.
350
+
351
+ An `_AppendAction` repeated zero times IS the flag not given: argparse
352
+ would answer `error: the following arguments are required: --focus`,
353
+ and `json_schema` already says `minItems: 1`. Counting `[]` as present
354
+ let `to_argv` build argv the CLI then refused with exit 2 -- the one
355
+ thing this validation exists to prevent -- and reported as "missing"
356
+ is what argparse itself would have called it.
357
+ """
358
+ if f.name not in arguments:
359
+ return True
360
+ return f.kind == "array" and arguments[f.name] == []
361
+
362
+
363
+ # -- argv becomes a call ----------------------------------------------------
364
+ def from_argv(ts: ToolSchema, argv: list[str]) -> dict:
365
+ """`{dest: value}` for argv WITHOUT the command word (P25).
366
+
367
+ Argparse's own parse, so what the CLI would refuse is refused here
368
+ in the same words -- as a `Rejection`, never as the process exit
369
+ argparse reaches for on a command line."""
370
+ parser = parser_for(ts)
371
+ stderr = io.StringIO()
372
+ try:
373
+ with contextlib.redirect_stderr(stderr):
374
+ namespace = parser.parse_args(list(argv))
375
+ except (argparse.ArgumentError, SystemExit) as exc:
376
+ raise Rejection("bad_fields", (),
377
+ stderr.getvalue().strip() or str(exc)) from None
378
+ parsed = vars(namespace)
379
+ defaults = {a.dest: a.default for a in parser._actions}
380
+ call = {}
381
+ for f in ts.fields:
382
+ if f.name not in parsed:
383
+ continue
384
+ value = parsed[f.name]
385
+ if value is None or value == [] or value is False:
386
+ continue
387
+ if f.name in defaults and value == defaults[f.name]:
388
+ continue
389
+ call[f.name] = value
390
+ return call