@ponythewhite/base-context 1.0.14 → 1.0.16

package/skills/bounded-inspect/src/bounded_inspect/__init__.py

@@ -0,0 +1,313 @@
+"""Bounded file evidence. Select lazily; emit one shared-budget JSON bundle."""
+
+import argparse
+import json
+import os
+import stat
+import sys
+from dataclasses import dataclass
+
+__all__ = ["text", "json_fields", "emit"]
+
+
+@dataclass(frozen=True)
+class _Selection:
+    kind: str
+    path: str
+    options: dict
+
+
+def text(path, *, head_lines=None, tail_lines=None, start_line=None, end_line=None, cursor=None):
+    """Select UTF-8 lines (1-based, inclusive), or resume a returned byte cursor."""
+    modes = sum(value is not None for value in (head_lines, tail_lines, start_line, cursor))
+    if modes > 1 or (end_line is not None and start_line is None):
+        raise ValueError("choose head, tail, line range, or cursor")
+    for value in (head_lines, tail_lines, start_line, end_line):
+        if value is not None and (not isinstance(value, int) or value < 1):
+            raise ValueError("line counts must be positive integers")
+    if start_line is not None and end_line is not None and end_line < start_line:
+        raise ValueError("end_line precedes start_line")
+    if modes == 0:
+        head_lines = 25
+    return _Selection("text", os.fspath(path), dict(head=head_lines, tail=tail_lines,
+                      start=start_line, end=end_line, cursor=dict(cursor) if cursor else cursor))
+
+
+def json_fields(path, *, pointers, max_source_bytes=65536):
+    """Select exact RFC 6901 pointers; missing is distinct from JSON null."""
+    pointers = tuple(pointers)
+    if any(not isinstance(p, str) or (p and not p.startswith("/")) for p in pointers):
+        raise ValueError("pointers must be empty (root) or start with /")
+    if max_source_bytes < 0:
+        raise ValueError("max_source_bytes must be nonnegative")
+    return _Selection("json", os.fspath(path), dict(pointers=pointers, cap=max_source_bytes))
+
+
+def _version(info):
+    return [info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns, info.st_ctime_ns]
+
+
+class _JsonNumber(str):
+    """A number token validated by json.loads, not converted through float/int."""
+
+
+def _serialized(value):
+    if isinstance(value, _JsonNumber):
+        return str(value)
+    if isinstance(value, dict):
+        return "{" + ",".join(_serialized(key) + ":" + _serialized(item) for key, item in value.items()) + "}"
+    if isinstance(value, list):
+        return "[" + ",".join(_serialized(item) for item in value) + "]"
+    return json.dumps(value, ensure_ascii=True, allow_nan=False, separators=(",", ":"))
+
+
+def _encoded(bundle):
+    # Count the complete wire envelope, including escaping and the final newline.
+    while True:
+        rendered = _serialized(bundle) + "\n"
+        size = len(rendered.encode("utf-8"))
+        if bundle["output_bytes"] == size:
+            return rendered
+        bundle["output_bytes"] = size
+
+
+def _read(handle, count, bundle):
+    data = handle.read(max(0, min(count, bundle["limits"]["source_bytes"] - bundle["source_bytes"])))
+    bundle["source_bytes"] += len(data)
+    return data
+
+
+def _cursor(path, version, offset, line, start, end, warnings):
+    return dict(path=path, version=version, offset=offset, line=line,
+                start_line=start, end_line=end, warnings=warnings)
+
+
+def _text(handle, selection, version, bundle):
+    options = selection.options
+    size = version[2]
+    cap = bundle["limits"]["source_bytes"] - bundle["source_bytes"]
+    cursor = options["cursor"]
+    warnings = []
+    offset, line = 0, 1
+    start, end = options["start"] or 1, options["end"] or options["head"]
+    if cursor is not None:
+        if cursor.get("path") != selection.path or cursor.get("version") != version:
+            return {"status": "changed_source", "next": None}, None
+        try:
+            offset, line = cursor["offset"], cursor["line"]
+            start, end = cursor["start_line"], cursor["end_line"]
+            warnings = cursor["warnings"]
+            if not isinstance(offset, int) or not 0 <= offset <= size:
+                raise ValueError()
+        except (KeyError, TypeError, ValueError):
+            return {"status": "invalid_cursor", "next": None}, None
+    elif options["tail"] is not None:
+        offset = max(0, size - cap)
+        line = 1 if offset == 0 else None
+        end = None
+    handle.seek(offset)
+    raw = _read(handle, size - offset, bundle)
+    if options["tail"] is not None:
+        # Work backwards only within the bounded suffix, never scan the prefix.
+        boundaries = [i + 1 for i, value in enumerate(raw) if value == 10 and i + 1 < len(raw)]
+        needed = options["tail"]
+        cut = boundaries[-needed] if len(boundaries) >= needed else 0
+        if offset and not cut:
+            warnings.append("tail_prefix_unread; absolute_line_unavailable")
+            while cut < len(raw) and raw[cut] & 0xC0 == 0x80:
+                cut += 1
+        if line is not None:
+            line += raw[:cut].count(b"\n")
+        offset += cut
+        raw = raw[cut:]
+    # Seek a requested line in bounded chunks. Cursors can advance without text.
+    if line is not None:
+        while line < start:
+            newline = raw.find(b"\n")
+            if newline < 0:
+                offset += len(raw)
+                raw = b""
+                break
+            offset += newline + 1
+            raw = raw[newline + 1:]
+            line += 1
+        if end is not None:
+            limit = end - line + 1
+            if limit <= 0:
+                raw = b""
+            else:
+                pos = 0
+                for _ in range(limit):
+                    newline = raw.find(b"\n", pos)
+                    if newline < 0:
+                        break
+                    pos = newline + 1
+                else:
+                    raw = raw[:pos]
+    try:
+        decoded = raw.decode("utf-8")
+    except UnicodeDecodeError as error:
+        if error.reason != "unexpected end of data" or offset + len(raw) == size:
+            return {"status": "invalid_utf8", "byte": offset + error.start, "next": None}, None
+        decoded = raw[:error.start].decode("utf-8")
+    context = (selection.path, version, offset, line, start, end, warnings)
+    if not decoded:
+        seeking = line is not None and line < start and offset < size
+        done = offset == size or (end is not None and line is not None and line > end)
+        status = "complete" if done else "seeking" if seeking and raw == b"" and cap else "source_limit"
+        next_cursor = _cursor(*context) if status == "seeking" else None
+        return dict(status=status, text="", range={"bytes": [offset, offset], "line": line},
+                    next=next_cursor, warnings=warnings), None
+    return {}, (decoded, context)
+
+
+def _text_prefix(decoded, context, length):
+    path, version, offset, line, start, end, warnings = context
+    value = decoded[:length]
+    stop = offset + len(value.encode("utf-8"))
+    next_line = None if line is None else line + value.count("\n")
+    done = stop == version[2] or (end is not None and next_line is not None and next_line > end)
+    status = ("tail_window_limit" if warnings else "complete") if done else "partial" if length else "output_limit"
+    following = None if done or not length else _cursor(path, version, stop, next_line, start, end, warnings)
+    return dict(status=status, text=value, range={"bytes": [offset, stop], "line": line},
+                next=following, warnings=warnings)
+
+
+def _constant(value):
+    raise ValueError("nonstandard JSON constant")
+
+
+def _json(handle, selection, version, bundle):
+    cap = min(selection.options["cap"], bundle["limits"]["source_bytes"] - bundle["source_bytes"])
+    if version[2] > cap:
+        return {"status": "source_limit", "size_bytes": version[2], "source_ceiling": cap}, None
+    raw = _read(handle, version[2], bundle)
+    try:
+        data = json.loads(raw, parse_float=_JsonNumber, parse_int=_JsonNumber, parse_constant=_constant)
+    except (ValueError, UnicodeError, RecursionError):
+        return {"status": "invalid_json"}, None
+    fields = []
+    for pointer in selection.options["pointers"]:
+        value = data
+        try:
+            for part in pointer.split("/")[1:] if pointer else []:
+                if any(part[i:i + 2] not in ("~0", "~1") for i, ch in enumerate(part) if ch == "~"):
+                    raise ValueError()
+                part = part.replace("~1", "/").replace("~0", "~")
+                if isinstance(value, list):
+                    if not part.isascii() or not part.isdigit() or (len(part) > 1 and part[0] == "0"):
+                        raise KeyError()
+                    value = value[int(part)]
+                elif isinstance(value, dict):
+                    value = value[part]
+                else:
+                    raise KeyError()
+            fields.append(dict(pointer=pointer, status="ok", value=value))
+        except (KeyError, IndexError):
+            fields.append(dict(pointer=pointer, status="missing"))
+        except ValueError:
+            fields.append(dict(pointer=pointer, status="invalid_pointer"))
+    return {"status": "complete", "fields": [], "omitted_fields": len(fields)}, fields
+
+
+def emit(*selections, max_bytes=4096, max_source_bytes=65536):
+    """Print one JSON bundle, within shared source/output byte limits. Return None."""
+    if not isinstance(max_bytes, int) or max_bytes < 128:
+        raise ValueError("max_bytes must be at least 128 (refusal envelope)")
+    if not isinstance(max_source_bytes, int) or max_source_bytes < 0:
+        raise ValueError("max_source_bytes must be nonnegative")
+    if any(not isinstance(selection, _Selection) for selection in selections):
+        raise TypeError("emit accepts text/json_fields selectors")
+    bundle = dict(items=[], omitted={"from": 0, "count": len(selections), "reason": "output_budget"},
+                  source_bytes=0, output_bytes=0,
+                  limits={"output_bytes": max_bytes, "source_bytes": max_source_bytes})
+    if len(_encoded(bundle).encode("utf-8")) > max_bytes:
+        bundle = dict(status="output_limit", omitted_count=len(selections), source_bytes=0, output_bytes=0)
+        print(_encoded(bundle), end="")
+        return None
+    for index, selection in enumerate(selections):
+        before = bundle["source_bytes"]
+        item = dict(index=index, path=selection.path, kind=selection.kind)
+        details = None
+        try:
+            # Unbuffered regular files: the counter is actual bytes read, not requested bytes.
+            with open(selection.path, "rb", buffering=0) as handle:
+                info = os.fstat(handle.fileno())
+                if not stat.S_ISREG(info.st_mode):
+                    result = {"status": "not_regular_file"}
+                else:
+                    version = _version(info)
+                    item["version"] = version
+                    if selection.kind == "text":
+                        result, details = _text(handle, selection, version, bundle)
+                    else:
+                        result, details = _json(handle, selection, version, bundle)
+                    if _version(os.fstat(handle.fileno())) != version or _version(os.stat(selection.path)) != version:
+                        result, details = {"status": "changed_source", "next": None}, None
+                item.update(result)
+        except OSError as error:
+            item.update(status="unavailable", error=error.__class__.__name__, errno=error.errno)
+        item["source_bytes"] = bundle["source_bytes"] - before
+        bundle["items"].append(item)
+        bundle["omitted"].update({"from": index + 1, "count": len(selections) - index - 1})
+
+        def fits():
+            return len(_encoded(bundle).encode("utf-8")) <= max_bytes
+
+        if details is not None and selection.kind == "text":
+            decoded, context = details
+            item.update(_text_prefix(decoded, context, len(decoded)))
+            if not fits():
+                low, high = 0, len(decoded)
+                while low < high:
+                    middle = (low + high + 1) // 2
+                    item.update(_text_prefix(decoded, context, middle))
+                    if fits():
+                        low = middle
+                    else:
+                        high = middle - 1
+                item.update(_text_prefix(decoded, context, low))
+        elif details is not None:
+            for field_index, field in enumerate(details):
+                item["fields"].append(field)
+                item["omitted_fields"] = len(details) - field_index - 1
+                if not fits():
+                    item["fields"][-1] = dict(pointer=field["pointer"], status="value_limit")
+                    item["status"] = "partial"
+                    if not fits():
+                        item["fields"].pop()
+                        item["omitted_fields"] += 1
+                        break
+        if not fits():
+            bundle["items"].pop()
+            bundle["omitted"].update({"from": index, "count": len(selections) - index})
+            break
+    # Budget refusal may follow real I/O, so keep those source bytes in the envelope.
+    rendered = _encoded(bundle)
+    if len(rendered.encode("utf-8")) > max_bytes:
+        bundle = dict(status="output_limit", omitted_count=len(selections),
+                      source_bytes=bundle["source_bytes"], output_bytes=0)
+        rendered = _encoded(bundle)
+    print(rendered, end="")
+    return None
+
+
+def main():
+    """Standalone: stage this file once, then pass a small JSON request on stdin."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--max-bytes", type=int, default=4096)
+    parser.add_argument("--max-source-bytes", type=int, default=65536)
+    args = parser.parse_args()
+    request = json.load(sys.stdin)
+    selections = []
+    for entry in request:
+        entry = dict(entry)
+        kind, path = entry.pop("kind"), entry.pop("path")
+        if kind not in ("text", "json"):
+            parser.error("kind must be text or json")
+        selections.append((text if kind == "text" else json_fields)(path, **entry))
+    emit(*selections, max_bytes=args.max_bytes, max_source_bytes=args.max_source_bytes)
+
+
+if __name__ == "__main__":
+    main()

package/skills/bounded-inspect/src/bounded_inspect/__main__.py

@@ -0,0 +1,3 @@
+from . import main
+
+main()

package/skills/job-watch/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: job-watch
+description: Watch launched jobs with native completion callbacks or scheduled read-only probes. Park owned continuation, suppress unchanged status, and deliver prepared evidence for failures, completion, changes, or required reports.
+---
+
+# Job Watch
+
+Use for repeated checks or jobs that outlive a short tool call. Tiny commands do not need a watch. Launch once with `bash()` or an authorized project helper. This skill never launches a job, retries a run, starts the next stage, or completes a goal.
+
+```python
+job = bash(existing_authorized_command)
+w = await job_watch.watch(
+    job, job_id="run-1", completion_source="handle",
+    probe_command=existing_read_only_probe_command,
+    interval="5m", notify="terminal", report_every="5m", fields=["updates", "wall_seconds"],
+)
+await job_watch.park([w["id"]])
+```
+
+Continue useful independent work instead of parking when possible. `park` returns immediately. It holds only automatic goal/autonomous continuation until an event from a selected watch. The goal stays active. User messages and unrelated queued work still run. End the turn after parking; do not poll or sleep.
+
+## API
+
+- `await watch(job=None, *, job_id=None, completion_source, probe_command=None, interval="5m", notify="terminal", fields=None, report_every=None, deadline=None, probe_timeout=30)` registers once. Repeating the same active resource registration returns its existing watch. `fields` selects top-level progress keys for cached status, required reports, and `notify="changes"`. Include every metric needed in reports. Observation time never counts as a change. Intervals use existing schedule syntax, with a ten-second minimum. `deadline` is an ISO date; timeout is seconds.
+- `await status(id=None)` returns cached snapshots, not a new probe.
+- `await park(ids)` registers a wait without blocking the cell.
+- `await unregister(id)` stops observation. It is idempotent and never kills the monitored job. It may cancel an in-flight probe.
+
+Set `completion_source="probe"` for detached remote jobs. A successful SSH launcher exit is **not** remote completion. Probe-only registration requires `job_id`. A probe command must be an already authorized, noninteractive, read-only command in the project's native environment. Do not pass notebook closures. The command prints one JSON object of at most 16 KiB:
+
+```json
+{"observed_at":"2026-09-28T12:00:00Z","job_id":"run-1","state":"running","progress":{"updates":12,"wall_seconds":45},"attention":[],"evidence":["runs/run-1/metrics.json"]}
+```
+
+Use strings for exact identifiers and precision-sensitive values. Unsafe integers, nonfinite numbers, and precision-losing numeric tokens are rejected as unavailable observations.
+
+States are `running`, `succeeded`, `failed`, `cancelled`, and `unknown`. Preserve units, configuration/run identity, unavailable values, and comparison eligibility in selected fields. Put project-specific threshold or quality-gate warnings in `attention`. Missing/partial JSON or transport failure means unavailable evidence, not permission to restart training. New observability problems and terminal failures remain visible; repeated identical problems are suppressed.
+
+Checks do not require reports. Omit `report_every` unless the user requires periodic reports. Required reports include a prepared snapshot even when values did not change. Delayed observations show lateness; they do not pretend to have run on time. Notifications are about 2 KiB. Large fields are explicitly omitted and captured probe output remains in the supplied file locator. Bash may already have discarded output; use explicit project log files when complete execution evidence matters.
+
+Consume delivered evidence; inspect raw sources only for decisions. Compaction does not recreate a watch. Clean shutdown retains undelivered reports with their original IDs. If shutdown interrupts delivery and its acknowledgement, recovery reports delivery as unknown; it does not claim exactly-once crash recovery. After restart, only an authoritative probe can reconcile a job; a lost handle becomes unknown. Never attach by PID or relaunch automatically. Imported/forked declarations do not acquire ownership. Preserve resource exclusivity, authorized run counts, and stop conditions. Unregister at the requested endpoint.
+
+Pending watch state is limited to 64 KiB (less under smaller source limits). If undelivered evidence fills it, prior reports remain; monitoring stops with unknown, a reason, and a retained locator. This is not successful cadence preservation. The job keeps running. Resume delivery, unregister exhausted watches, and explicitly register again. No automatic retry.

package/skills/job-watch/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "job-watch"
+version = "0.1.0"
+description = "Base Context owned job monitoring over the kernel host bridge"
+requires-python = ">=3.10"
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/job_watch"]

package/skills/job-watch/src/job_watch/__init__.py

@@ -0,0 +1,61 @@
+"""Monitor authorized jobs without model polling. Launch with bash(), not this skill."""
+from __future__ import annotations
+from typing import Any, Literal
+from rlm import host_request
+from rlm.bash import BashHandle
+try:
+    from rlm import job_watch as _runtime
+except ImportError:
+    _runtime = None
+
+
+async def watch(
+    job: BashHandle | None = None, *, job_id: str | None = None,
+    completion_source: Literal["handle", "probe"], probe_command: str | None = None,
+    interval: str = "5m", notify: Literal["terminal", "changes"] = "terminal",
+    fields: list[str] | None = None, report_every: str | None = None,
+    deadline: str | None = None, probe_timeout: float = 30,
+) -> dict[str, Any]:
+    """Register once. Probe commands must be authorized, noninteractive, and read-only.
+
+    A probe prints JSON: observed_at, job_id, state, progress, attention, evidence.
+    fields selects top-level progress keys; timestamps never trigger progress changes.
+    completion_source='probe' is required for detached remote jobs, including SSH launchers.
+    """
+    if _runtime is None:
+        raise RuntimeError("job-watch requires a runtime with job_watch_probe_v1; no watch was registered")
+    if completion_source not in {"handle", "probe"}:
+        raise ValueError("completion_source must be handle or probe")
+    if job is None and (completion_source == "handle" or not job_id):
+        raise ValueError("handle completion requires a BashHandle; probe-only watches require job_id")
+    resource = _runtime.identity(job) if job is not None else f"probe:{job_id}"
+    result = await host_request("job_watch.watch", {
+        "job_id": job_id or resource, "resource_id": resource,
+        "completion_source": completion_source, "probe_command": probe_command,
+        "interval": interval, "notify": notify, "fields": fields or [],
+        "report_every": report_every, "deadline": deadline, "timeout_ms": probe_timeout * 1000,
+    })
+    if job is not None and completion_source == "handle":
+        _runtime.bind(job, result["id"], result["generation"], job_id or resource)
+    return result
+
+
+async def status(id: str | None = None) -> dict[str, Any]:
+    """Return cached state only; never launch a probe or a model turn."""
+    return await host_request("job_watch.status", {} if id is None else {"id": id})
+
+
+async def park(ids: list[str]) -> dict[str, Any]:
+    """Declare no further owned continuation until a selected event. Returns immediately.
+
+    User messages and unrelated queued work still run. This does not pause the goal.
+    """
+    return await host_request("job_watch.park", {"ids": ids})
+
+
+async def unregister(id: str) -> dict[str, Any]:
+    """Stop watching, not the job. Repeated calls are harmless."""
+    result = await host_request("job_watch.unregister", {"id": id})
+    if _runtime is not None:
+        _runtime.unbind(id)
+    return result

package/skills/rlm-heartbeat/SKILL.md

@@ -12,8 +12,8 @@ replace, pause, resume, or clear that user-level heartbeat.
 Call directly from the Python REPL:
 
 ```python
-await rlm_heartbeat.create("check test progress", interval="5m", label="tests")
-await rlm_heartbeat.create("watch build", delivery_mode="follow_up")
+await rlm_heartbeat.create("review current priorities", interval="30m", label="review")
+await rlm_heartbeat.create("review pending decisions", delivery_mode="follow_up")
 await rlm_heartbeat.list()
 await rlm_heartbeat.update("job-id", status="pause")
 await rlm_heartbeat.delete("job-id")
@@ -46,9 +46,13 @@ the session when it is busy:
 
 - Use this when the user asks you to start, create, schedule, or manage your own
   heartbeat without explicitly referring to `/heartbeat`.
-- Use this only for agent-internal recurring checks and long-running task
-  coordination.
+- Use this for recurring work that needs a model decision. For deterministic
+  job checks, prefer `job-watch` when available: it probes before deciding whether
+  to wake the model. Preserve every required report and any explicit heartbeat
+  request; do not silently replace the user's schedule.
 - Do not use this skill to satisfy a user's request to configure `/heartbeat`;
   that is a separate user-level surface.
-- Keep heartbeat instructions specific and actionable so each recurring turn
-  knows exactly what to inspect or continue.
+- Name the current authoritative state and an existing parameterized project
+  helper in monitoring instructions. Do not copy the same detailed status into
+  heartbeats, messages, notebook variables, and status documents. Reuse the
+  helper with current inputs; repetition never authorizes new jobs.