tactus 0.29.3__py3-none-any.whl → 0.30.0__py3-none-any.whl

tactus/__init__.py

@@ -5,7 +5,7 @@ Tactus provides a declarative workflow engine for AI agents with pluggable
 backends for storage, HITL, and chat recording.
 """
 
-__version__ = "0.29.3"
+__version__ = "0.30.0"
 
 # Core exports
 from tactus.core.runtime import TactusRuntime

tactus/broker/server.py

@@ -10,7 +10,7 @@ import json
 import logging
 import os
 import ssl
-from collections.abc import Callable
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Optional
@@ -19,7 +19,12 @@ import anyio
 from anyio.streams.buffered import BufferedByteReceiveStream
 from anyio.streams.tls import TLSStream
 
-from tactus.broker.protocol import read_message_anyio, write_message_anyio
+from tactus.broker.protocol import (
+    read_message,
+    read_message_anyio,
+    write_message,
+    write_message_anyio,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -446,6 +451,7 @@ class BrokerServer(_BaseBrokerServer):
             openai_backend=openai_backend, tool_registry=tool_registry, event_handler=event_handler
         )
         self.socket_path = Path(socket_path)
+        self._server: asyncio.AbstractServer | None = None
 
     async def start(self) -> None:
         # Most platforms enforce a short maximum length for AF_UNIX socket paths.
@@ -461,19 +467,286 @@ class BrokerServer(_BaseBrokerServer):
             self.socket_path.unlink()
 
         self._server = await asyncio.start_unix_server(
-            self._handle_connection, path=str(self.socket_path)
+            self._handle_connection_asyncio, path=str(self.socket_path)
         )
         logger.info(f"[BROKER] Listening on UDS: {self.socket_path}")
 
     async def aclose(self) -> None:
         await super().aclose()
 
+        if self._server is not None:
+            self._server.close()
+            try:
+                await self._server.wait_closed()
+            finally:
+                self._server = None
+
         try:
             if self.socket_path.exists():
                 self.socket_path.unlink()
         except Exception:
             logger.debug("[BROKER] Failed to unlink socket path", exc_info=True)
 
+    async def _handle_connection_asyncio(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        try:
+            req = await read_message(reader)
+            req_id = req.get("id")
+            method = req.get("method")
+            params = req.get("params") or {}
+
+            async def write_event(event: dict[str, Any]) -> None:
+                await write_message(writer, event)
+
+            if not req_id or not method:
+                await write_event(
+                    {
+                        "id": req_id or "",
+                        "event": "error",
+                        "error": {"type": "BadRequest", "message": "Missing id/method"},
+                    }
+                )
+                return
+
+            if method == "events.emit":
+                await self._handle_events_emit_asyncio(req_id, params, write_event)
+                return
+
+            if method == "llm.chat":
+                await self._handle_llm_chat_asyncio(req_id, params, write_event)
+                return
+
+            if method == "tool.call":
+                await self._handle_tool_call_asyncio(req_id, params, write_event)
+                return
+
+            await write_event(
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": "MethodNotFound", "message": f"Unknown method: {method}"},
+                }
+            )
+
+        except Exception as e:
+            logger.debug("[BROKER] Connection handler error", exc_info=True)
+            try:
+                await write_message(
+                    writer,
+                    {
+                        "id": "",
+                        "event": "error",
+                        "error": {"type": type(e).__name__, "message": str(e)},
+                    },
+                )
+            except Exception:
+                pass
+        finally:
+            try:
+                writer.close()
+                await writer.wait_closed()
+            except Exception:
+                pass
+
+    async def _handle_events_emit_asyncio(
+        self,
+        req_id: str,
+        params: dict[str, Any],
+        write_event: Callable[[dict[str, Any]], Awaitable[None]],
+    ) -> None:
+        event = params.get("event")
+        if not isinstance(event, dict):
+            await write_event(
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": "BadRequest", "message": "params.event must be an object"},
+                }
+            )
+            return
+
+        try:
+            if self._event_handler is not None:
+                self._event_handler(event)
+        except Exception:
+            logger.debug("[BROKER] event_handler raised", exc_info=True)
+
+        await write_event({"id": req_id, "event": "done", "data": {"ok": True}})
+
+    async def _handle_tool_call_asyncio(
+        self,
+        req_id: str,
+        params: dict[str, Any],
+        write_event: Callable[[dict[str, Any]], Awaitable[None]],
+    ) -> None:
+        name = params.get("name")
+        args = params.get("args") or {}
+
+        if not isinstance(name, str) or not name:
+            await write_event(
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": "BadRequest", "message": "params.name must be a string"},
+                }
+            )
+            return
+        if not isinstance(args, dict):
+            await write_event(
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": "BadRequest", "message": "params.args must be an object"},
+                }
+            )
+            return
+
+        try:
+            result = self._tools.call(name, args)
+        except KeyError:
+            await write_event(
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {
+                        "type": "ToolNotAllowed",
+                        "message": f"Tool not allowlisted: {name}",
+                    },
+                }
+            )
+            return
+        except Exception as e:
+            logger.debug("[BROKER] tool.call error", exc_info=True)
+            await write_event(
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": type(e).__name__, "message": str(e)},
+                }
+            )
+            return
+
+        await write_event({"id": req_id, "event": "done", "data": {"result": result}})
+
+    async def _handle_llm_chat_asyncio(
+        self,
+        req_id: str,
+        params: dict[str, Any],
+        write_event: Callable[[dict[str, Any]], Awaitable[None]],
+    ) -> None:
+        provider = params.get("provider") or "openai"
+        if provider != "openai":
+            await write_event(
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {
+                        "type": "UnsupportedProvider",
+                        "message": f"Unsupported provider: {provider}",
+                    },
+                }
+            )
+            return
+
+        model = params.get("model")
+        messages = params.get("messages")
+        stream = bool(params.get("stream", False))
+        temperature = params.get("temperature")
+        max_tokens = params.get("max_tokens")
+
+        if not isinstance(model, str) or not model:
+            await write_event(
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": "BadRequest", "message": "params.model must be a string"},
+                }
+            )
+            return
+        if not isinstance(messages, list):
+            await write_event(
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": "BadRequest", "message": "params.messages must be a list"},
+                }
+            )
+            return
+
+        try:
+            if stream:
+                stream_iter = await self._openai.chat(
+                    model=model,
+                    messages=messages,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                    stream=True,
+                )
+
+                full_text = ""
+                async for chunk in stream_iter:
+                    try:
+                        delta = chunk.choices[0].delta
+                        text = getattr(delta, "content", None)
+                    except Exception:
+                        text = None
+
+                    if not text:
+                        continue
+
+                    full_text += text
+                    await write_event({"id": req_id, "event": "delta", "data": {"text": text}})
+
+                await write_event(
+                    {
+                        "id": req_id,
+                        "event": "done",
+                        "data": {
+                            "text": full_text,
+                            "usage": {
+                                "prompt_tokens": 0,
+                                "completion_tokens": 0,
+                                "total_tokens": 0,
+                            },
+                        },
+                    }
+                )
+                return
+
+            resp = await self._openai.chat(
+                model=model,
+                messages=messages,
+                temperature=temperature,
+                max_tokens=max_tokens,
+                stream=False,
+            )
+            text = ""
+            try:
+                text = resp.choices[0].message.content or ""
+            except Exception:
+                text = ""
+
+            await write_event(
+                {
+                    "id": req_id,
+                    "event": "done",
+                    "data": {
+                        "text": text,
+                        "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
+                    },
+                }
+            )
+        except Exception as e:
+            logger.debug("[BROKER] llm.chat error", exc_info=True)
+            await write_event(
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": type(e).__name__, "message": str(e)},
+                }
+            )
+
 
 class TcpBrokerServer(_BaseBrokerServer):
     """
@@ -499,6 +772,7 @@ class TcpBrokerServer(_BaseBrokerServer):
         self.port = port
         self.ssl_context = ssl_context
         self.bound_port: int | None = None
+        self._serve_task: asyncio.Task[None] | None = None
 
     async def start(self) -> None:
         # Create AnyIO TCP listener (doesn't block, just binds to port)
@@ -515,3 +789,21 @@ class TcpBrokerServer(_BaseBrokerServer):
         logger.info(
             f"[BROKER] Listening on {scheme}: {self.host}:{self.bound_port if self.bound_port is not None else self.port}"
         )
+
+        # Unlike asyncio's start_server(), AnyIO listeners don't automatically start
+        # serving on enter; they require an explicit serve() loop. Run it in the
+        # background for the duration of the async context manager.
+        if self._serve_task is None or self._serve_task.done():
+            self._serve_task = asyncio.create_task(self.serve(), name="tactus-broker-tcp-serve")
+
+    async def aclose(self) -> None:
+        task = self._serve_task
+        self._serve_task = None
+        if task is not None and not task.done():
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+
+        await super().aclose()

tactus/cli/app.py

@@ -28,6 +28,7 @@ from rich.table import Table
 from tactus.core import TactusRuntime
 from tactus.core.yaml_parser import ProcedureYAMLParser, ProcedureConfigError
 from tactus.validation import TactusValidator, ValidationMode
+from tactus.formatting import TactusFormatter, FormattingError
 from tactus.adapters.memory import MemoryStorage
 from tactus.adapters.file_storage import FileStorage
 from tactus.adapters.cli_hitl import CLIHITLHandler
@@ -1116,6 +1117,56 @@ def validate(
         raise typer.Exit(1)
 
 
+@app.command("format")
+def format_(
+    workflow_file: Path = typer.Argument(..., help="Path to workflow file (.tac or .lua)"),
+    check: bool = typer.Option(
+        False,
+        "--check",
+        help="Don't write files back; exit 1 if changes are needed",
+    ),
+    stdout: bool = typer.Option(False, "--stdout", help="Write formatted code to stdout"),
+):
+    """
+    Format a Tactus Lua DSL file.
+
+    Currently enforces semantic indentation using 2-space soft tabs.
+    """
+    if not workflow_file.exists():
+        console.print(f"[red]Error:[/red] Workflow file not found: {workflow_file}")
+        raise typer.Exit(1)
+
+    if workflow_file.suffix not in [".tac", ".lua"]:
+        console.print("[red]Error:[/red] Formatting is only supported for .tac/.lua files")
+        raise typer.Exit(1)
+
+    formatter = TactusFormatter(indent_width=2)
+    source_content = workflow_file.read_text()
+
+    try:
+        result = formatter.format_source(source_content)
+    except FormattingError as e:
+        console.print(f"[red]✗[/red] {e}")
+        raise typer.Exit(1)
+
+    if stdout:
+        sys.stdout.write(result.formatted)
+        return
+
+    if check:
+        if result.changed:
+            console.print(f"[red]✗ Would reformat:[/red] {workflow_file}")
+            raise typer.Exit(1)
+        console.print(f"[green]✓ Already formatted:[/green] {workflow_file}")
+        return
+
+    if result.changed:
+        workflow_file.write_text(result.formatted)
+        console.print(f"[green]✓ Formatted:[/green] {workflow_file}")
+    else:
+        console.print(f"[green]✓ No changes:[/green] {workflow_file}")
+
+
 @app.command()
 def info(
     workflow_file: Path = typer.Argument(..., help="Path to workflow file (.tac or .lua)"),

tactus/formatting/__init__.py

@@ -0,0 +1,7 @@
+"""
+Formatting utilities for Tactus Lua DSL files.
+"""
+
+from .formatter import TactusFormatter, FormattingError
+
+__all__ = ["TactusFormatter", "FormattingError"]

tactus/formatting/formatter.py

@@ -0,0 +1,437 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Iterable, Set
+
+from antlr4 import CommonTokenStream, InputStream
+from antlr4.Token import Token
+from antlr4.TokenStreamRewriter import TokenStreamRewriter
+
+from tactus.validation.error_listener import TactusErrorListener
+from tactus.validation.generated.LuaLexer import LuaLexer
+from tactus.validation.generated.LuaParser import LuaParser
+
+
+class FormattingError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class FormatResult:
+    formatted: str
+    changed: bool
+
+
+class TactusFormatter:
+    """
+    ANTLR-based formatter for Tactus Lua DSL files.
+
+    Current scope: semantic indentation (2-space soft tabs) while preserving
+    token text, comments, and multi-line string/comment contents.
+    """
+
+    def __init__(self, indent_width: int = 2):
+        if indent_width <= 0:
+            raise ValueError("indent_width must be positive")
+        self._indent_width = indent_width
+
+    def format_source(self, source: str) -> FormatResult:
+        original_source = source
+        token_stream, error_listener = self._parse_to_tokens(source)
+        if error_listener.errors:
+            first = error_listener.errors[0]
+            raise FormattingError(f"Cannot format invalid source: {first.message}")
+
+        tokens = list(token_stream.tokens)
+        source = _rewrite_token_text(source, tokens, token_stream)
+        protected_lines = self._protected_lines_from_multiline_tokens(tokens)
+        indent_by_line = self._indentation_by_line(tokens, num_lines=_count_lines(source))
+
+        formatted = _rewrite_leading_indentation(
+            source,
+            indent_by_line=indent_by_line,
+            indent_width=self._indent_width,
+            protected_lines=protected_lines,
+        )
+        return FormatResult(formatted=formatted, changed=(formatted != original_source))
+
+    def format_file(self, file_path: Path) -> FormatResult:
+        source = file_path.read_text()
+        return self.format_source(source)
+
+    def _parse_to_tokens(self, source: str) -> tuple[CommonTokenStream, TactusErrorListener]:
+        input_stream = InputStream(source)
+        lexer = LuaLexer(input_stream)
+        token_stream = CommonTokenStream(lexer)
+        token_stream.fill()
+
+        parser = LuaParser(token_stream)
+        error_listener = TactusErrorListener()
+        parser.removeErrorListeners()
+        parser.addErrorListener(error_listener)
+        parser.start_()
+        return token_stream, error_listener
+
+    def _protected_lines_from_multiline_tokens(self, tokens: Iterable[Token]) -> Set[int]:
+        protected: Set[int] = set()
+        for tok in tokens:
+            text = getattr(tok, "text", None)
+            if not text or "\n" not in text:
+                continue
+
+            if tok.type in (LuaLexer.LONGSTRING, LuaLexer.COMMENT):
+                start = int(getattr(tok, "line", 0) or 0)
+                if start <= 0:
+                    continue
+                end = start + text.count("\n")
+                protected.update(range(start, end + 1))
+        return protected
+
+    def _indentation_by_line(self, tokens: Iterable[Token], *, num_lines: int) -> Dict[int, int]:
+        line_to_default_tokens: Dict[int, list[Token]] = {}
+        for tok in tokens:
+            if tok.type == Token.EOF:
+                continue
+            if tok.channel != Token.DEFAULT_CHANNEL:
+                continue
+            line_to_default_tokens.setdefault(int(tok.line), []).append(tok)
+
+        open_tokens = {
+            LuaLexer.THEN,
+            LuaLexer.DO,
+            LuaLexer.FUNCTION,
+            LuaLexer.REPEAT,
+            LuaLexer.OCU,  # {
+            LuaLexer.ELSE,
+            LuaLexer.ELSEIF,
+        }
+        close_tokens = {
+            LuaLexer.END,
+            LuaLexer.UNTIL,
+            LuaLexer.CCU,  # }
+        }
+        dedent_at_line_start = close_tokens | {LuaLexer.ELSE, LuaLexer.ELSEIF}
+
+        indent_level = 0
+        indent_by_line: Dict[int, int] = {}
+
+        for line_no in range(1, num_lines + 1):
+            tokens_on_line = line_to_default_tokens.get(line_no, [])
+            first = tokens_on_line[0] if tokens_on_line else None
+
+            if first is not None and first.type in dedent_at_line_start:
+                indent_level = max(0, indent_level - 1)
+
+            indent_by_line[line_no] = indent_level
+
+            handled_first_dedent = first is not None and first.type in dedent_at_line_start
+            for idx, tok in enumerate(tokens_on_line):
+                if tok.type in close_tokens:
+                    if idx == 0 and handled_first_dedent:
+                        continue
+                    indent_level = max(0, indent_level - 1)
+                if tok.type in open_tokens:
+                    indent_level += 1
+
+        return indent_by_line
+
+
+def _count_lines(source: str) -> int:
+    if not source:
+        return 1
+    return source.count("\n") + 1
+
+
+def _split_line_ending(line: str) -> tuple[str, str]:
+    if line.endswith("\r\n"):
+        return line[:-2], "\r\n"
+    if line.endswith("\n"):
+        return line[:-1], "\n"
+    if line.endswith("\r"):
+        return line[:-1], "\r"
+    return line, ""
+
+
+def _rewrite_leading_indentation(
+    source: str,
+    *,
+    indent_by_line: Dict[int, int],
+    indent_width: int,
+    protected_lines: Set[int],
+) -> str:
+    lines = source.splitlines(keepends=True)
+    out: list[str] = []
+
+    for i, raw in enumerate(lines, start=1):
+        if i in protected_lines:
+            out.append(raw)
+            continue
+
+        body, ending = _split_line_ending(raw)
+        if body.strip() == "":
+            out.append(ending)
+            continue
+
+        desired = " " * (indent_width * max(0, int(indent_by_line.get(i, 0))))
+        stripped = body.lstrip(" \t")
+        out.append(desired + stripped + ending)
+
+    return "".join(out)
+
+
+_LONGSTRING_OPEN_RE = re.compile(r"^\[(?P<eq>=*)\[(?P<body>.*)\](?P=eq)\]$", re.DOTALL)
+
+
+def _rewrite_token_text(source: str, tokens: list[Token], token_stream: CommonTokenStream) -> str:
+    """
+    Token-based, semantic rewrites (idempotent):
+    - Indent embedded Specifications longstrings.
+    - Enforce spaces around '=' (within a single line).
+    - Remove trailing commas in multi-line table constructors.
+    """
+    rewriter = TokenStreamRewriter(token_stream)
+    default_tokens: list[Token] = [
+        t for t in tokens if t.type != Token.EOF and t.channel == Token.DEFAULT_CHANNEL
+    ]
+
+    _apply_specifications_longstring_rewrites(tokens, default_tokens, rewriter)
+    _apply_assignment_spacing(default_tokens, tokens, rewriter)
+    _apply_comma_spacing(default_tokens, tokens, rewriter)
+    _apply_binary_operator_spacing(default_tokens, tokens, rewriter)
+    _apply_multiline_table_trailing_comma_removal(default_tokens, tokens, rewriter)
+
+    rewritten = rewriter.getDefaultText()
+    return rewritten if rewritten != source else source
+
+
+def _apply_specifications_longstring_rewrites(
+    tokens: list[Token], default_tokens: list[Token], rewriter: TokenStreamRewriter
+) -> None:
+    longstring_token_indices: list[int] = []
+    for idx, tok in enumerate(default_tokens):
+        if tok.type != LuaLexer.LONGSTRING:
+            continue
+        if _is_specifications_call_longstring(default_tokens, idx):
+            longstring_token_indices.append(tok.tokenIndex)
+
+    for token_index in longstring_token_indices:
+        tok = tokens[token_index]
+        new_text = _format_specifications_longstring_text(tok.text or "")
+        if new_text != (tok.text or ""):
+            rewriter.replaceIndex(token_index, new_text)
+
+
+def _apply_assignment_spacing(
+    default_tokens: list[Token], tokens: list[Token], rewriter: TokenStreamRewriter
+) -> None:
+    for i, tok in enumerate(default_tokens):
+        if tok.type != LuaLexer.EQ:
+            continue
+        if i == 0 or i + 1 >= len(default_tokens):
+            continue
+
+        prev = default_tokens[i - 1]
+        nxt = default_tokens[i + 1]
+        if prev.line != tok.line or nxt.line != tok.line:
+            continue
+
+        # Normalize the hidden token region between prev and '=' to a single space.
+        if prev.tokenIndex + 1 <= tok.tokenIndex - 1:
+            rewriter.replaceRange(prev.tokenIndex + 1, tok.tokenIndex - 1, " ")
+        else:
+            rewriter.insertBeforeIndex(tok.tokenIndex, " ")
+
+        # Normalize the hidden token region between '=' and next to a single space.
+        if tok.tokenIndex + 1 <= nxt.tokenIndex - 1:
+            rewriter.replaceRange(tok.tokenIndex + 1, nxt.tokenIndex - 1, " ")
+        else:
+            rewriter.insertAfterToken(tok, " ")
+
+
+def _has_comment_or_newline_between(tokens: list[Token], left: Token, right: Token) -> bool:
+    if left.tokenIndex + 1 > right.tokenIndex - 1:
+        return False
+    for t in tokens[left.tokenIndex + 1 : right.tokenIndex]:
+        if t.type in (LuaLexer.NL, LuaLexer.COMMENT):
+            return True
+    return False
+
+
+def _apply_comma_spacing(
+    default_tokens: list[Token], tokens: list[Token], rewriter: TokenStreamRewriter
+) -> None:
+    for i, tok in enumerate(default_tokens):
+        if tok.type != LuaLexer.COMMA:
+            continue
+        if i == 0 or i + 1 >= len(default_tokens):
+            continue
+        prev = default_tokens[i - 1]
+        nxt = default_tokens[i + 1]
+        if prev.line != tok.line or nxt.line != tok.line:
+            continue
+        if _has_comment_or_newline_between(tokens, prev, tok) or _has_comment_or_newline_between(
+            tokens, tok, nxt
+        ):
+            continue
+
+        if prev.tokenIndex + 1 <= tok.tokenIndex - 1:
+            rewriter.replaceRange(prev.tokenIndex + 1, tok.tokenIndex - 1, "")
+
+        if tok.tokenIndex + 1 <= nxt.tokenIndex - 1:
+            rewriter.replaceRange(tok.tokenIndex + 1, nxt.tokenIndex - 1, " ")
+        else:
+            rewriter.insertAfterToken(tok, " ")
+
+
+def _apply_binary_operator_spacing(
+    default_tokens: list[Token], tokens: list[Token], rewriter: TokenStreamRewriter
+) -> None:
+    binary_ops = {
+        LuaLexer.PLUS,
+        LuaLexer.MINUS,
+        LuaLexer.STAR,
+        LuaLexer.SLASH,
+        LuaLexer.PER,
+        LuaLexer.SS,  # //
+        LuaLexer.DD,  # ..
+        LuaLexer.CARET,
+        LuaLexer.PIPE,
+        LuaLexer.AMP,
+        LuaLexer.LL,
+        LuaLexer.GG,
+        LuaLexer.LT,
+        LuaLexer.GT,
+        LuaLexer.LE,
+        LuaLexer.GE,
+        LuaLexer.EE,
+        LuaLexer.SQEQ,
+        LuaLexer.AND,
+        LuaLexer.OR,
+    }
+    unary_preceders = {
+        LuaLexer.EQ,
+        LuaLexer.COMMA,
+        LuaLexer.OP,
+        LuaLexer.OB,
+        LuaLexer.OCU,
+        LuaLexer.CC,  # '::'
+        LuaLexer.THEN,
+        LuaLexer.DO,
+        LuaLexer.ELSE,
+        LuaLexer.ELSEIF,
+        LuaLexer.RETURN,
+        LuaLexer.FOR,
+        LuaLexer.WHILE,
+        LuaLexer.IF,
+        LuaLexer.IN,
+        LuaLexer.AND,
+        LuaLexer.OR,
+    } | binary_ops
+
+    for i, tok in enumerate(default_tokens):
+        if tok.type not in binary_ops:
+            continue
+        if i == 0 or i + 1 >= len(default_tokens):
+            continue
+        prev = default_tokens[i - 1]
+        nxt = default_tokens[i + 1]
+        if prev.line != tok.line or nxt.line != tok.line:
+            continue
+        if _has_comment_or_newline_between(tokens, prev, tok) or _has_comment_or_newline_between(
+            tokens, tok, nxt
+        ):
+            continue
+
+        if tok.type in (LuaLexer.MINUS, LuaLexer.PLUS) and prev.type in unary_preceders:
+            continue
+
+        if prev.tokenIndex + 1 <= tok.tokenIndex - 1:
+            rewriter.replaceRange(prev.tokenIndex + 1, tok.tokenIndex - 1, " ")
+        else:
+            rewriter.insertBeforeIndex(tok.tokenIndex, " ")
+
+        if tok.tokenIndex + 1 <= nxt.tokenIndex - 1:
+            rewriter.replaceRange(tok.tokenIndex + 1, nxt.tokenIndex - 1, " ")
+        else:
+            rewriter.insertAfterToken(tok, " ")
+
+
+def _apply_multiline_table_trailing_comma_removal(
+    default_tokens: list[Token], tokens: list[Token], rewriter: TokenStreamRewriter
+) -> None:
+    stack: list[int] = []
+    for idx, tok in enumerate(default_tokens):
+        if tok.type == LuaLexer.OCU:
+            stack.append(idx)
+            continue
+        if tok.type != LuaLexer.CCU:
+            continue
+        if not stack:
+            continue
+        open_idx = stack.pop()
+        open_tok = default_tokens[open_idx]
+        close_tok = tok
+        if open_tok.line == close_tok.line:
+            continue
+
+        j = idx - 1
+        if j <= open_idx:
+            continue
+        last = default_tokens[j]
+        if last.type == LuaLexer.COMMA:
+            rewriter.replaceIndex(last.tokenIndex, "")
+
+
+def _is_specifications_call_longstring(default_tokens: list[Token], longstring_idx: int) -> bool:
+    # Accept: Specifications(LONGSTRING) where LONGSTRING is the first argument.
+    if longstring_idx < 1:
+        return False
+    prev = default_tokens[longstring_idx - 1]
+    if prev.type == LuaLexer.OP and longstring_idx >= 2:
+        name = default_tokens[longstring_idx - 2]
+        return name.type == LuaLexer.NAME and (name.text or "") == "Specifications"
+    name = prev
+    return name.type == LuaLexer.NAME and (name.text or "") == "Specifications"
+
+
+def _format_specifications_longstring_text(text: str) -> str:
+    match = _LONGSTRING_OPEN_RE.match(text)
+    if not match:
+        return text
+
+    eq = match.group("eq")
+    body = match.group("body")
+    open_delim = f"[{eq}["
+    close_delim = f"]{eq}]"
+
+    formatted_body = _shift_longstring_body_indent_once(body, shift_spaces=2)
+    return f"{open_delim}{formatted_body}{close_delim}"
+
+
+def _shift_longstring_body_indent_once(body: str, *, shift_spaces: int) -> str:
+    lines = body.splitlines(keepends=True)
+    already_formatted = False
+    for line in lines:
+        raw, _ending = _split_line_ending(line)
+        if raw.strip() == "":
+            continue
+        expanded = raw.replace("\t", "  ")
+        already_formatted = expanded.startswith(" " * shift_spaces)
+        break
+
+    if already_formatted:
+        return body
+
+    out: list[str] = []
+    prefix = " " * shift_spaces
+    for line in lines:
+        raw, ending = _split_line_ending(line)
+        if raw.strip() == "":
+            out.append(raw + ending)
+            continue
+
+        expanded = raw.replace("\t", "  ")
+        out.append(prefix + expanded + ending)
+    return "".join(out)

{tactus-0.29.3.dist-info → tactus-0.30.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tactus
-Version: 0.29.3
+Version: 0.30.0
 Summary: Tactus: Lua-based DSL for agentic workflows
 Project-URL: Homepage, https://github.com/AnthusAI/Tactus
 Project-URL: Documentation, https://github.com/AnthusAI/Tactus/tree/main/docs
@@ -1665,6 +1665,12 @@ Agents:
 # Validate syntax and structure
 tactus validate workflow.tac
 
+# Format a workflow file (2-space indentation + normalized spacing)
+tactus format workflow.tac
+
+# Check formatting without rewriting (exit 1 if changes needed)
+tactus format workflow.tac --check
+
 # Run BDD specifications
 tactus test workflow.tac
 
@@ -1675,6 +1681,8 @@ tactus test workflow.tac --runs 10
 tactus eval workflow.tac --runs 10
 ```
 
+The `format` command uses Tactus's Lua parser to reindent and normalize whitespace while preserving the structure of the code.
+
 ### Understanding Output
 
 The CLI displays several types of events:

{tactus-0.29.3.dist-info → tactus-0.30.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-tactus/__init__.py,sha256=tMi2Yv0ZZKlamq-Nm6tLBtJkGFbkiibwUBQTz5Vmo7w,1245
+tactus/__init__.py,sha256=bxlJnTV0P7LYntLZsAFANekhPuuBckJ5pE-BXXAWwAo,1245
 tactus/adapters/__init__.py,sha256=lU8uUxuryFRIpVrn_KeVK7aUhsvOT1tYsuE3FOOIFpI,289
 tactus/adapters/broker_log.py,sha256=mIjARt1Q6ouWVbVri6zep1e8tzm9y28l4WOEdqiK39Q,2849
 tactus/adapters/cli_hitl.py,sha256=3dH58du0lN4k-OvQrAHrAqHFqBjolqNKFb94JaNHtn8,6964
@@ -18,10 +18,10 @@ tactus/backends/pytorch_backend.py,sha256=I7H7UTa_Scx9_FtmPWn-G4noadaNVEQj-9Kjtj
 tactus/broker/__init__.py,sha256=UTvqLofrgE3c4m6u2iNOg5R7BrS4dmfzMRO4Oq_0A9U,396
 tactus/broker/client.py,sha256=sDi1Cimuv0zH5S4n597nnUy_qis7pLBZf5IkwF81oDc,8618
 tactus/broker/protocol.py,sha256=fnVgMKU_R7oK2xBATnrYSH_r2R-yOmV2o_pJYw1JvVk,5238
-tactus/broker/server.py,sha256=ciP6FkPBfenfzrTNzkr6If7kQFs4B7mLU77A0hh7y_8,17154
+tactus/broker/server.py,sha256=3FCaz7gWHcK1ZCKsRPVkhGCof2ND798FTv-lDirZQek,26783
 tactus/broker/stdio.py,sha256=JXkEz-PCU3IQXNkt16YJtYmwkR43eS6CfjxAHc-YCfQ,439
 tactus/cli/__init__.py,sha256=kVhdCkwWEPdt3vn9si-iKvh6M9817aOH6rLSsNzRuyg,80
-tactus/cli/app.py,sha256=97lrjIQxDGM5PuvPZx9CeTZc0CyT1tBhLOl98oej3zE,83496
+tactus/cli/app.py,sha256=DCRJRQoxJbGCOizmOT6krSqSJHZ0ujNpTluZoG56cMg,85186
 tactus/cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tactus/core/__init__.py,sha256=TK5rWr3HmOO_igFa5ESGp6teWwS58vnvQhIWqkcgqwk,880
 tactus/core/config_manager.py,sha256=u90XChTeb2reZ3I6c3o_zI2UlzlFCNtL9-NhE1Vm6L0,31577
@@ -48,6 +48,8 @@ tactus/dspy/history.py,sha256=0yGi3P5ruRUPoRyaCWsUDeuEYYsfproc_7pMVZuhmUo,5980
 tactus/dspy/module.py,sha256=sJdFS-5A4SpuiMLjbwiZJCvg3pTtEx8x8MRVaqjCQ2I,15423
 tactus/dspy/prediction.py,sha256=nnofvBPGFX7bvYdTVcEMVcIXC5EVrRQ21QsnC1PRHeU,9758
 tactus/dspy/signature.py,sha256=jdLHBa5BOEBwXTfmLui6fjViEDQDhdUzQm2__STHquU,6053
+tactus/formatting/__init__.py,sha256=pkwfAJwMxdRha2oahXoUrVjk6if7QH5d1U5t5dF2fXc,162
+tactus/formatting/formatter.py,sha256=DfHp977t5reMPIWZwRChRE5Yflw7xGgTNUM0AOcS8LQ,14510
 tactus/ide/__init__.py,sha256=1fSC0xWP-Lq5wl4FgDq7SMnkvZ0DxXupreTl3ZRX1zw,143
 tactus/ide/coding_assistant.py,sha256=GgmspWIn9IPgBK0ZYapeISIOrcDfRyK7yyPDPV85r8g,12184
 tactus/ide/server.py,sha256=TSCnx0Sc9EhRnX5Kl3dUZk-REzxUWmkDoPeHHZ4-AHg,94459
@@ -152,8 +154,8 @@ tactus/validation/generated/LuaParserVisitor.py,sha256=ageKSmHPxnO3jBS2fBtkmYBOd
 tactus/validation/generated/__init__.py,sha256=5gWlwRI0UvmHw2fnBpj_IG6N8oZeabr5tbj1AODDvjc,196
 tactus/validation/grammar/LuaLexer.g4,sha256=t2MXiTCr127RWAyQGvamkcU_m4veqPzSuHUtAKwalw4,2771
 tactus/validation/grammar/LuaParser.g4,sha256=ceZenb90BdiZmVdOxMGj9qJk3QbbWVZe5HUqPgoePfY,3202
-tactus-0.29.3.dist-info/METADATA,sha256=ke3bCpB7ffcOBTiOWyjKRYtwpgUb9v9MVCdwpQrfPqM,58441
-tactus-0.29.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-tactus-0.29.3.dist-info/entry_points.txt,sha256=vWseqty8m3z-Worje0IYxlioMjPDCoSsm0AtY4GghBY,47
-tactus-0.29.3.dist-info/licenses/LICENSE,sha256=ivohBcAIYnaLPQ-lKEeCXSMvQUVISpQfKyxHBHoa4GA,1066
-tactus-0.29.3.dist-info/RECORD,,
+tactus-0.30.0.dist-info/METADATA,sha256=OJMinYvQWWE8vKf6K1mFNBOKRdu5YK6ZPMpjC9AWbRA,58765
+tactus-0.30.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tactus-0.30.0.dist-info/entry_points.txt,sha256=vWseqty8m3z-Worje0IYxlioMjPDCoSsm0AtY4GghBY,47
+tactus-0.30.0.dist-info/licenses/LICENSE,sha256=ivohBcAIYnaLPQ-lKEeCXSMvQUVISpQfKyxHBHoa4GA,1066
+tactus-0.30.0.dist-info/RECORD,,