@vibelord/lanes 1.2.0 → 1.3.0

package/payload/lanes/container/lane-mcp

@@ -18,7 +18,8 @@ capture's text, a sent text or a note), rotated to .1 past 1 MiB.
 Read tools (the lanes of THIS container: what ~/.lz/registry.json and ~/.lz/status.json hold):
   lanes_whoami                 which lane this agent runs in ($LANE_ID, else its tmux pane's session)
   lanes_list [workspace] [needs_you] [agent]   every lane here with its state and agent
-  lanes_status <lane>          one lane in full: registry facts, observed state, agent, tmux liveness, hook sidecar
+  lanes_status <lane>          one lane in full: registry facts, observed state, agent, documents (`docs`), tmux
+                               liveness, hook sidecar, and the lane's latest publish receipt (`published`)
   lanes_capture <lane> [lines] the last N (1–500, default 100) non-blank lines of that lane's screen and scrollback
 
 Write tools (LNS-35). Each answers JSON: on success what changed, what picks it up (`picked_up_by`) and when
@@ -34,8 +35,12 @@ terminal); `lanes sync` publishes the change (lanes-statusd starts one within ~1
   lanes_signal <status> [note]  report this agent's own status (and a one-line note) through lane-signal; the report
                                stands until the agent's next tool call, prompt or permission prompt, and the end of
                                its turn keeps it (lane-signal's EXPLICIT rule)
+  lanes_publish <path> [title] [for] [kind]   put a file of this container on the Lanes docs page from this agent's
+                               own lane (plan W10 W4): a request in ~/.lz/state/publish/<lane>/ that the host's
+                               lanes-docsd takes within ~5 s, answering in <id>.receipt.json (lane_core.publish)
 Human-only by omission (no tool exists): ending or closing a lane, interrupting it (C-c or any key that is not
-printable text), opening or attaching one, uploads, the host's sync/gc/ensure, renaming a tmux session, and any
+printable text), opening or attaching one, uploads (a person's file into a lane: the Docs page or the desktop drop;
+an agent's own file goes the other way, lanes_publish), the host's sync/gc/ensure, renaming a tmux session, and any
 edit of an adopted (`lanes register`ed, `--x-`) session — those stay with a person on the boards or the host.
 """
 import json
@@ -71,6 +76,8 @@ PATH_MAX, COMMAND_MAX = 1024, 1024
 SYNC_LATENCY_S, STATUS_LATENCY_S = 15, 5
 SYNC_PICKUP = 'lanes sync'
 STATUS_PICKUP = 'lanes-statusd'
+# A publish request: lanes-docsd's own pick-up cycle (5 s, plan W10 W4) takes it and writes the receipt back.
+PUBLISH_PICKUP, PUBLISH_LATENCY_S = C.PUBLISH_PICKUP, C.PUBLISH_LATENCY_S
 SESSION_VARS = ('CLAUDE_CODE_SESSION_ID', 'CODEX_THREAD_ID')   # the agent's session id, when its env carries one
 # How long a lanes_signal report holds against the agent's own hooks (lane-signal's EXPLICIT rule, DEF-1801).
 SIGNAL_STANDS = ('your next tool call, a new prompt, a permission prompt, a failed turn or the session\'s end; the end '
@@ -86,7 +93,9 @@ INSTRUCTIONS = ('Lanes tools for the workspace container this agent runs in. A l
                 'display name, lanes_new declares and starts a new lane, lanes_send types text into a lane (refused '
                 'while its agent is working or waiting for an approval unless force: true), lanes_signal reports '
                 'your own status with a short note. Every write answers what changed, what picks it up and when; a '
-                'refusal answers a machine code and what a person can do instead. Ending, interrupting or attaching '
+                'refusal answers a machine code and what a person can do instead. lanes_publish puts a file of this '
+                'container on the Lanes docs page, where the people on your boards open it (the host takes it within '
+                'about 5 s; lanes_status shows the receipt as `published`). Ending, interrupting or attaching '
                 'a lane is a person\'s call: no tool does it.')
 
 ID_PATTERN = '^[A-Za-z0-9_][A-Za-z0-9_.-]*$'
@@ -139,8 +148,9 @@ TOOLS = (
     _tool('lanes_status', 'Show one lane',
           'One lane in full: the registry facts (board, display name, kind, tmux socket and session, the declaring '
           'terminals.json and repository), the host\'s observation (state, agent, attached clients, viewers, last '
-          'activity, size, stale), whether its tmux session is alive now (null when tmux did not answer) and its '
-          'lane-signal hook sidecar.',
+          'activity, size, stale, and `docs`: how many documents the docs page holds for the lane and when the '
+          'newest arrived), whether its tmux session is alive now (null when tmux did not answer), its '
+          'lane-signal hook sidecar, and `published`: the lane\'s latest publish receipt (id, url, at, outcome).',
           {'lane': LANE_ARG}, required=('lane',)),
     _tool('lanes_capture', 'Read a lane\'s screen',
           'The last `lines` non-blank lines of a tmux lane\'s screen and scrollback, as plain text (wrapped lines '
@@ -213,6 +223,25 @@ TOOLS = (
                     'description': f'What you are doing, one line of at most {NOTE_MAX} characters; "" clears it. '
                                    'Kept while the report stands or its status repeats.'}},
           required=('status',), hints=_writes(False, True)),
+    _tool('lanes_publish', 'Publish a file to the docs page',
+          'Put a file of this container on the Lanes docs page, from the lane this agent runs in: Markdown (with '
+          'Mermaid diagrams) is rendered there, an HTML or SVG artifact opens sandboxed on its own page, any other '
+          'file is offered as a download. Writes a request the host\'s lanes-docsd takes within about 5 s; it reads '
+          'the file itself, checks its sha256 against the one answered here and writes a receipt that lanes_status '
+          'shows as `published` (outcome ok with the document\'s url, or refused with the reason). The file must be '
+          f'under /home/coder (every link resolved) and at most {C.PUBLISH_MAX >> 20} MiB. Who sees it: `for`, else '
+          'the person who last opened this lane, else every member whose record lists the lane\'s board.',
+          {'path': {'type': 'string', 'minLength': 1, 'maxLength': PATH_MAX,
+                    'description': 'The file: an absolute path under /home/coder.'},
+           'title': {'type': 'string', 'maxLength': C.TITLE_MAX,
+                     'description': f'The title the docs page shows, one line of at most {C.TITLE_MAX} characters; '
+                                    'default: the file name.'},
+           'for': {'type': 'string', 'minLength': 1, 'maxLength': C.LOGIN_MAX,
+                   'description': 'The tailnet login of the member the document is for (only they see it).'},
+           'kind': {'type': 'string', 'enum': list(C.PUBLISH_KINDS),
+                    'description': 'md, html, svg or file; default: from the extension (.md/.markdown, .html/.htm, '
+                                   '.svg, anything else file).'}},
+          required=('path',), hints=_writes(False, False)),
 )
 TOOL_BY_NAME = {tool['name']: tool for tool in TOOLS}
 WRITE_TOOLS = frozenset(tool['name'] for tool in TOOLS if not tool['annotations']['readOnlyHint'])
@@ -280,6 +309,13 @@ HUMAN = {
     'tmux_failed': 'lanes_status says whether the lane is running.',
     'signal_not_written': 'A person checks the lane-signal install (`lanes install-container <container>` on the '
                           'host).',
+    'outside_home': 'Publish a file under /home/coder: copy it there first (a link that leads outside is refused).',
+    'not_a_file': 'Pass an existing regular file (not a directory, FIFO or device).',
+    'too_large': f'A published file is at most {C.PUBLISH_MAX >> 20} MiB: publish a smaller one, or tell a person '
+                 'where the file is.',
+    'invalid_title': 'A title is one line of printable text without leading or trailing spaces.',
+    'invalid_for': 'Pass one tailnet login (as `anna@example.com`), or leave `for` out.',
+    'invalid_kind': 'Pass md, html, svg or file, or leave `kind` out.',
     'refused': 'A person takes it from here.',
 }
 
@@ -384,7 +420,9 @@ def agent_summary(agent):
     return {key: agent[key] for key in ('harness', 'status', 'name', 'since') if agent.get(key) is not None}
 
 
-OBSERVED = ('attached', 'viewers', 'activity', 'size', 'stale')
+# The observed keys a row copies from ~/.lz/status.json when present. `docs` ({n, at}: the documents the docs cockpit
+# holds for the lane, plan W10 W7) is an additive result key within wire v1, absent while the lane has none.
+OBSERVED = ('attached', 'viewers', 'activity', 'size', 'stale', 'docs')
 
 
 class Server:
@@ -643,6 +681,9 @@ class Server:
             alive = None if code in (124, 127) else code == 0
         out['alive'] = alive
         out['hook'] = C.hook_agent(self.root / 'state' / 'hooks', lane, self.proc) or None
+        published = C.latest_receipt(self.root, lane)   # plan W10 W4: read here, in the container, never via status.json
+        if published:
+            out['published'] = published
         out['status'] = freshness(status)
         return out
 
@@ -1066,6 +1107,24 @@ class Server:
                 'picked_up_by': STATUS_PICKUP, 'expected_within_s': STATUS_LATENCY_S}
 
 
+    def tool_publish(self, arguments):
+        found = C.whoami(self.root, self.environ)
+        lane = found['lane']
+        if not lane:
+            refuse('not_in_lane', found.get('why') or 'this agent runs in no lane',
+                   'lanes_publish publishes from the lane this agent runs in: start the agent inside a lane (for '
+                   'Codex, `lane mcp install` passes the lane\'s variables to this server).')
+        try:
+            local = self.local(arguments['path'])
+        except ValueError as error:
+            refuse('outside_home', f'{error}: pass an absolute path under {C.CONTAINER_HOME}')
+        out = C.publish(self.root, self.home, local, lane, title=arguments.get('title'),
+                        for_login=arguments.get('for'), kind=arguments.get('kind'))
+        return {**out, 'changed': f'{out["request"]}: a publish request for {out["path"]} ({out["kind"]}, '
+                                  f'{out["bytes"]} bytes, sha256 {out["sha256"]})',
+                'picked_up_by': PUBLISH_PICKUP, 'expected_within_s': PUBLISH_LATENCY_S}
+
+
 def main(argv):
     if argv:
         if argv[0] in ('-h', '--help'):

package/payload/lanes/container/lane_core.py

@@ -25,6 +25,9 @@ sees, and `lane-mcp` may write nothing but protocol frames to its stdout.
     test_lane_mcp_write.HostRules), and `declared_name`, which finds a registry lane's declared terminal in its file.
   * the agents' MCP entries: `mcpServers.lanes` in ~/.claude.json and `[mcp_servers.lanes]` (command + env_vars) in
     ~/.codex/config.toml, planned as a diff, written with a `.bak-<UTC>` copy, atomically and only when missing.
+  * publish requests (plan W10 W4): `publish` writes ~/.lz/state/publish/<lane>/<id>.json for `lane publish` and
+    lane-mcp's `lanes_publish` (the file hashed once, the id in docs_store's grammar: `new_publish_id`), and
+    `latest_receipt` reads the `<id>.receipt.json` the host's lanes-docsd writes back (`lanes_status`'s `published`).
 """
 import difflib
 import json
@@ -1138,3 +1141,178 @@ def mcp_apply(home, agents=MCP_AGENTS, command=MCP_COMMAND):
         results.append({'agent': agent, 'path': path, 'status': status, 'backup': saved,
                         'why': refusal[0] if refusal else None})
     return results
+
+
+# ------------------------------------------------------------------------------------------------ publishing (W10 W4)
+# `lane publish <file>` and lane-mcp's `lanes_publish` put a file of this container on the Lanes docs page. Nothing here
+# copies the file anywhere: the request names it, and the host's lanes-docsd reads it through /proc/<container init>/root
+# on its own 5 s cycle (it trusts nothing in the request: the path is resolved inside the container again, the bytes
+# hashed again), stores it in the docs store and writes `<id>.receipt.json` back beside the request, which it removes.
+#
+#   ~/.lz/state/publish/<lane id>/<id>.json           the request (DM-LANES-PUBLISH-REQUEST): {v: 1, path, title, kind,
+#                                                     claimed_sha256, mime, bytes, for}, `path` the file's absolute path
+#                                                     in this container with every link resolved
+#   ~/.lz/state/publish/<lane id>/<id>.receipt.json   the host's answer (DM-LANES-PUBLISH-RECEIPT): {v: 1, id, request,
+#                                                     sha256, bytes, url, at, outcome: ok|refused, reason?}
+
+PUBLISH_KINDS = ('md', 'html', 'svg', 'file')   # docs_store.KINDS without `upload` (a person's upload is the host's)
+PUBLISH_MAX = 32 << 20                          # docsd.PUBLISH_LIMIT: a larger file is refused here and on the host
+PUBLISH_PICKUP = 'lanes-docsd'                  # what takes a request (docsd.Pickup)
+PUBLISH_LATENCY_S = 5                           # docsd.PICKUP_INTERVAL: one pick-up cycle
+PUBLISH_DIR = ('state', 'publish')              # under ~/.lz
+PUBLISH_ID = re.compile(r'[a-z0-9]{10,20}')     # docs_store.ID_RE
+RECEIPT_SUFFIX = '.receipt.json'
+TITLE_MAX = 200                                 # docs_store.MAX_TITLE
+LOGIN_MAX = 254                                 # members.MAX_LOGIN
+ID_TIME = '0123456789abcdefghijklmnopqrstuvwxyz'   # docs_store.BASE36: epoch seconds, zero-padded to 6
+ID_RANDOM = 'abcdefghijklmnopqrstuvwxyz234567'     # docs_store.BASE32: 6 random characters
+KIND_BY_SUFFIX = {'.md': 'md', '.markdown': 'md', '.html': 'html', '.htm': 'html', '.svg': 'svg'}
+MIME_BY_SUFFIX = {'.md': 'text/markdown', '.markdown': 'text/markdown', '.html': 'text/html', '.htm': 'text/html',
+                  '.svg': 'image/svg+xml', '.txt': 'text/plain', '.json': 'application/json', '.csv': 'text/csv',
+                  '.pdf': 'application/pdf', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+                  '.gif': 'image/gif', '.webp': 'image/webp'}   # = libexec/docs_store.MIME_BY_SUFFIX (DEF-1920)
+REFUSED_TEXT = frozenset(('Cc', 'Cf', 'Cs', 'Co', 'Cn', 'Zl', 'Zp'))   # members.REFUSED_CATEGORIES
+
+
+def new_publish_id(now=None):
+    """A request id in docs_store's grammar (`new_id`: base36 epoch seconds zero-padded to 6, then 6 random base32),
+    pinned equal to it by test_lane_publish. The container cannot import the host's store."""
+    import secrets
+    seconds, digits = int(time.time() if now is None else now), ''
+    while True:
+        seconds, rest = divmod(seconds, 36)
+        digits = ID_TIME[rest] + digits
+        if not seconds:
+            break
+    return digits.rjust(6, '0') + ''.join(secrets.choice(ID_RANDOM) for _ in range(6))
+
+
+def publish_kind(path, kind=None):
+    """`kind` when given (one of PUBLISH_KINDS), else from the file name: .md/.markdown md, .html/.htm html, .svg svg,
+    anything else file. LaneError `invalid_kind`."""
+    if kind is None or kind == '':
+        return KIND_BY_SUFFIX.get(os.path.splitext(str(path))[1].lower(), 'file')
+    if kind not in PUBLISH_KINDS:
+        raise LaneError(f'kind {kind!r} is not one of {", ".join(PUBLISH_KINDS)}', 'invalid_kind')
+    return kind
+
+
+def _one_line(value, what, limit, blanks, code):
+    """`value` when it is one printable line of at most `limit` characters without outer blanks (members._text's rule;
+    `blanks`: inner spaces allowed), else LaneError `code`. The host checks it again."""
+    if (not isinstance(value, str) or not value or len(value) > limit or value != value.strip()
+            or any(unicodedata.category(char) in REFUSED_TEXT for char in value)
+            or (not blanks and any(char.isspace() for char in value))):
+        raise LaneError(f'{what} is one line of at most {limit} printable characters'
+                        + ('' if blanks else ' without blanks'), code)
+    return value
+
+
+def publish_dir(root, lane):
+    return Path(root).joinpath(*PUBLISH_DIR, lane)
+
+
+def publish(root, home, path, lane, title=None, for_login=None, kind=None, now=None):
+    """Write a publish request for the file at `path` (as this process reaches it) from `lane` -> {id, lane, path,
+    kind, title, for, bytes, sha256, request, receipt}: `path` the file's container path, `request`/`receipt` the
+    container paths of the request and of the receipt lanes-docsd writes. `root` is ~/.lz and `home` /home/coder as
+    this process reaches them (themselves in a container, test directories otherwise).
+
+    The file must resolve (os.path.realpath) inside `home` to a regular file of at most PUBLISH_MAX bytes; it is read
+    once, never through a link at its last component and never blocking on a FIFO, to hash it (`claimed_sha256`, which
+    the host compares with its own). Refusals (LaneError): `not_in_lane`, `invalid_title`, `invalid_for`,
+    `invalid_kind`, `outside_home`, `not_a_file`, `too_large`. The request is replaced atomically (0644); nothing else
+    is written."""
+    import hashlib
+    import mimetypes
+    if not isinstance(lane, str) or not LANE_RE.fullmatch(lane):
+        raise LaneError('this agent runs in no lane to publish from', 'not_in_lane')
+    title = None if title in (None, '') else _one_line(title, 'a title', TITLE_MAX, True, 'invalid_title')
+    for_login = None if for_login in (None, '') else _one_line(for_login, 'a login', LOGIN_MAX, False, 'invalid_for')
+    base = os.path.realpath(str(home))
+    real = os.path.realpath(str(path))
+    if not real.startswith(base.rstrip(os.sep) + os.sep):
+        raise LaneError(f'{path} is not a file under {CONTAINER_HOME} (with every link resolved): only this '
+                        'container\'s home can be published', 'outside_home')
+    kind = publish_kind(real, kind)
+    try:
+        fd = os.open(real, os.O_RDONLY | os.O_NONBLOCK | getattr(os, 'O_NOFOLLOW', 0) | getattr(os, 'O_CLOEXEC', 0))
+    except OSError as error:
+        raise LaneError(f'{path}: {error.strerror or "cannot be opened"}', 'not_a_file') from None
+    digest, size = hashlib.sha256(), 0
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode):
+            raise LaneError(f'{path} is not a regular file', 'not_a_file')
+        if info.st_size > PUBLISH_MAX:
+            raise LaneError(f'{path} is larger than {PUBLISH_MAX >> 20} MiB', 'too_large')
+        while True:
+            chunk = os.read(fd, 1 << 16)
+            if not chunk:
+                break
+            size += len(chunk)
+            if size > PUBLISH_MAX:
+                raise LaneError(f'{path} is larger than {PUBLISH_MAX >> 20} MiB', 'too_large')
+            digest.update(chunk)
+    finally:
+        os.close(fd)
+    container = CONTAINER_HOME + '/' + os.path.relpath(real, base).replace(os.sep, '/')
+    name = os.path.basename(real)
+    # The same table as libexec/docs_store.MIME_BY_SUFFIX: Python's built-in map gained `.md` only in 3.12, so the
+    # request's `mime` must not depend on the interpreter (the host compares nothing on it, but receipts carry it).
+    mime, encoding = MIME_BY_SUFFIX.get(os.path.splitext(name)[1].lower()), None
+    if not mime:
+        mime, encoding = mimetypes.MimeTypes().guess_type(name)   # the built-in table, as the host's
+    request = {'v': 1, 'path': container, 'title': title, 'kind': kind, 'claimed_sha256': digest.hexdigest(),
+               'mime': mime if mime and not encoding else 'application/octet-stream', 'bytes': size, 'for': for_login}
+    directory = publish_dir(root, lane)
+    directory.mkdir(parents=True, exist_ok=True)
+    for _ in range(16):
+        request_id = new_publish_id(now)
+        if not any(os.path.lexists(str(directory / (request_id + suffix))) for suffix in ('.json', RECEIPT_SUFFIX)):
+            break
+    else:
+        raise LaneError('could not mint a free request id', 'refused')
+    atomic_replace(directory / f'{request_id}.json', json.dumps(request, ensure_ascii=False, indent=1) + '\n', 0o644)
+    where = LZ + '/' + '/'.join(PUBLISH_DIR) + f'/{lane}/{request_id}'
+    return {'id': request_id, 'lane': lane, 'path': container, 'kind': kind, 'title': title, 'for': for_login,
+            'bytes': size, 'sha256': request['claimed_sha256'], 'request': where + '.json',
+            'receipt': where + RECEIPT_SUFFIX}
+
+
+def latest_receipt(root, lane):
+    """The newest receipt lanes-docsd wrote back for `lane` (~/.lz/state/publish/<lane>/<id>.receipt.json; the latest
+    `at` — whole seconds —, then the file written last, then the id) as lanes_status shows it -> {id, url, at,
+    outcome, request, reason?}, or None (no receipt yet, or none that reads as one). Each file is read as a regular
+    file only (read_regular: no link, no FIFO)."""
+    if not isinstance(lane, str) or not LANE_RE.fullmatch(lane):
+        return None
+    directory = publish_dir(root, lane)
+    try:
+        names = os.listdir(str(directory))
+    except OSError:
+        return None
+    best = None
+    for name in names:
+        request_id = name[:-len(RECEIPT_SUFFIX)] if name.endswith(RECEIPT_SUFFIX) else ''
+        if not PUBLISH_ID.fullmatch(request_id):
+            continue
+        receipt = read_json(directory / name)
+        if not (isinstance(receipt, dict) and receipt.get('v') == 1 and isinstance(receipt.get('at'), str)
+                and receipt.get('outcome') in ('ok', 'refused')):
+            continue
+        try:
+            written = os.stat(str(directory / name), follow_symlinks=False).st_mtime_ns
+        except OSError:
+            continue
+        key = (receipt['at'], written, request_id)
+        if best is None or key > best[0]:
+            best = (key, request_id, receipt)
+    if best is None:
+        return None
+    _key, request_id, receipt = best
+    out = {'id': receipt.get('id'), 'url': receipt.get('url'), 'at': receipt['at'], 'outcome': receipt['outcome'],
+           'request': request_id}
+    if receipt['outcome'] == 'refused':
+        out['reason'] = receipt.get('reason')
+    return out