semora-coding 0.2.0__tar.gz

semora_coding-0.2.0/.gitignore

@@ -0,0 +1,28 @@
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.coverage
+htmlcov/
+.env
+.env.*
+!.env.example
+
+
+# Local tool/editor state — machine-specific, never pushed.
+.claude/
+.codecanvas/
+.vscode/
+
+
+# Superpowers design/spec scratch — working notes, not project documentation.
+docs/superpowers/
+
+# 로컬 자격증명 — 절대 커밋 금지.
+a.txt
+*.token

semora_coding-0.2.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.5
+Name: semora-coding
+Version: 0.2.0
+Summary: A coding agent's toolset, prompts and policies, assembled over the semora core.
+Project-URL: Homepage, https://github.com/donggyun112/semora
+Project-URL: Source, https://github.com/donggyun112/semora
+Project-URL: Changelog, https://github.com/donggyun112/semora/blob/main/CHANGELOG.md
+Author: donggyun112
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: langchain-core<2,>=1
+Requires-Dist: semora==0.2.0
+Description-Content-Type: text/markdown
+
+# semora-coding
+
+The coding-agent layer over the `semora` core: built-in tools (`read`, `write`, `edit`, `grep`,
+`glob`, `Bash`, `web_fetch`), system-prompt assembly, plan mode, goals, the skill catalog and
+deferred tool search.
+
+```
+uv add "semora[coding]"
+```
+
+It is a reference assembly. The core promises that a tool's effect happens once and that every
+decision about it has a seam; this package is one answer to what those tools and seams say to a
+model. Replace any of it — the core does not know it is here.

semora_coding-0.2.0/README.md

@@ -0,0 +1,13 @@
+# semora-coding
+
+The coding-agent layer over the `semora` core: built-in tools (`read`, `write`, `edit`, `grep`,
+`glob`, `Bash`, `web_fetch`), system-prompt assembly, plan mode, goals, the skill catalog and
+deferred tool search.
+
+```
+uv add "semora[coding]"
+```
+
+It is a reference assembly. The core promises that a tool's effect happens once and that every
+decision about it has a seam; this package is one answer to what those tools and seams say to a
+model. Replace any of it — the core does not know it is here.

semora_coding-0.2.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "semora-coding"
+version = "0.2.0"
+description = "A coding agent's toolset, prompts and policies, assembled over the semora core."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "donggyun112" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+urls = { Homepage = "https://github.com/donggyun112/semora", Source = "https://github.com/donggyun112/semora", Changelog = "https://github.com/donggyun112/semora/blob/main/CHANGELOG.md" }
+dependencies = [
+  "langchain-core>=1,<2",
+  "semora==0.2.0",
+]
+# The product layer the core used to carry: what a coding agent reads and edits with, the words
+# its plan mode and goal say, the catalog its skills are listed in. None of it decides whether an
+# effect happens once — that stays in `semora` — so none of it belongs in the distribution that
+# makes that promise. A reference assembly, installed on purpose, replaceable as a whole.
+
+[tool.uv.sources]
+semora = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/semora_coding"]

semora_coding-0.2.0/src/semora_coding/__init__.py

@@ -0,0 +1,7 @@
+"""The coding-agent layer over the semora core.
+
+`semora` decides whether an effect happens once and where each decision about it is made. This
+package is what a coding agent does with that: the tools it reads and edits with, the words its
+plan mode and goal say, the catalog its skills are listed in. Import the piece you assemble with —
+`semora_coding.builtins`, `.prompts`, `.plan_mode`, `.goal`, `.skills`, `.tool_search`.
+"""

semora_coding-0.2.0/src/semora_coding/builtins/__init__.py

@@ -0,0 +1,249 @@
+"""TS-compatible core built-in tool bundle.
+
+The bundle intentionally contains file/process tools plus ``web_fetch``. It does not include
+``web_search``; applications can add their own search provider when they need one.
+"""
+
+from __future__ import annotations
+
+from functools import partial
+from typing import Any
+
+from semora.workspace import ToolContext
+
+from ._exec import exec_is_read_only, exec_tool
+from ._files import edit_tool, read_tool, write_tool
+from ._search import glob_tool, grep_tool
+from ._types import (
+    BuiltinToolState,
+    ExecToolOptions,
+    Handler,
+    WebFetchResponse,
+    WebFetchSummarizer,
+    WebFetchToolOptions,
+    WebFetchTransport,
+    error_result,
+)
+from ._web import UrllibWebFetchTransport, web_fetch_tool
+
+__all__ = [
+    "BuiltinTools",
+    "ExecToolOptions",
+    "UrllibWebFetchTransport",
+    "WebFetchResponse",
+    "WebFetchSummarizer",
+    "WebFetchToolOptions",
+    "WebFetchTransport",
+    "builtin_tools",
+]
+
+
+class BuiltinTools:
+    """Context-aware implementation of the TS sandbox bundle plus ``web_fetch``."""
+
+    def __init__(
+        self,
+        *,
+        context: ToolContext | None = None,
+        exec_options: ExecToolOptions | None = None,
+        web_fetch_options: WebFetchToolOptions | None = None,
+        _state: BuiltinToolState | None = None,
+    ) -> None:
+        """Configure tool policy independently from a turn's workspace session."""
+        self._context = context or ToolContext(workdir=".")
+        self._exec_options = exec_options or ExecToolOptions()
+        self._web_fetch_options = web_fetch_options or WebFetchToolOptions()
+        self._state = _state or BuiltinToolState()
+        self._handlers: dict[str, Handler] = {
+            "read": read_tool,
+            "write": write_tool,
+            "edit": edit_tool,
+            "glob": glob_tool,
+            "grep": grep_tool,
+            "Bash": partial(exec_tool, options=self._exec_options),
+            "web_fetch": partial(web_fetch_tool, options=self._web_fetch_options),
+        }
+        self._definitions = _definitions(self._exec_options.allow_shell)
+
+    async def execute(self, name: str, call_id: str, arguments: Any) -> dict[str, Any]:
+        """Execute a named built-in against the currently bound context."""
+        handler = self._handlers.get(name)
+        if handler is None:
+            return error_result(f"Unknown tool: {name}")
+        return dict(await handler(call_id, arguments, self._context, self._state))
+
+    def get(self, name: str) -> dict[str, Any] | None:
+        """Return one model-visible tool definition."""
+        definition = self._definitions.get(name)
+        return dict(definition) if definition is not None else None
+
+    def list(self) -> list[dict[str, Any]]:
+        """Return the stable core set, deliberately excluding ``web_search``."""
+        return [dict(definition) for definition in self._definitions.values()]
+
+    def get_context(self) -> ToolContext:
+        """Return the immutable execution context currently bound to the tools."""
+        return self._context
+
+    def with_context(self, context: ToolContext) -> BuiltinTools:
+        """Bind a runtime workspace while retaining locks and fetch cache across turns."""
+        return BuiltinTools(
+            context=context,
+            exec_options=self._exec_options,
+            web_fetch_options=self._web_fetch_options,
+            _state=self._state,
+        )
+
+
+def builtin_tools(
+    *,
+    context: ToolContext | None = None,
+    exec_options: ExecToolOptions | None = None,
+    web_fetch_options: WebFetchToolOptions | None = None,
+) -> BuiltinTools:
+    """Create the standard bundle, optionally bound to a caller-managed workspace context."""
+    return BuiltinTools(
+        context=context,
+        exec_options=exec_options,
+        web_fetch_options=web_fetch_options,
+    )
+
+
+def _definitions(allow_shell: bool) -> dict[str, dict[str, Any]]:
+    return {
+        "read": {
+            "name": "read",
+            "description": (
+                "Read a file or directory from the workspace. Text is line-numbered and paged; "
+                "images return inline and Jupyter notebooks return readable cell text."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "offset": {"type": "number"},
+                    "limit": {"type": "number"},
+                    "pages": {"type": "string"},
+                },
+                "required": ["path"],
+            },
+            "is_read_only": True,
+            "is_concurrency_safe": True,
+        },
+        "write": {
+            "name": "write",
+            "description": "Create or replace a UTF-8 file inside the workspace.",
+            "parameters": {
+                "type": "object",
+                "properties": {"path": {"type": "string"}, "content": {"type": "string"}},
+                "required": ["path", "content"],
+            },
+            "is_read_only": False,
+            "is_concurrency_safe": False,
+        },
+        "edit": {
+            "name": "edit",
+            "description": "Replace an exact string in a UTF-8 workspace file.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "old_string": {"type": "string"},
+                    "new_string": {"type": "string"},
+                    "replace_all": {"type": "boolean"},
+                },
+                "required": ["path", "old_string", "new_string"],
+            },
+            "is_read_only": False,
+            "is_concurrency_safe": False,
+        },
+        "grep": {
+            "name": "grep",
+            "description": (
+                "Search workspace file contents with ripgrep, falling back to system grep. "
+                "Supports content, files_with_matches, and count output modes."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "pattern": {"type": "string"},
+                    "path": {"type": "string"},
+                    "glob": {"type": "string"},
+                    "type": {"type": "string"},
+                    "output_mode": {
+                        "type": "string",
+                        "enum": ["content", "files_with_matches", "count"],
+                    },
+                    "-A": {"type": "number"},
+                    "-B": {"type": "number"},
+                    "-C": {"type": "number"},
+                    "context": {"type": "number"},
+                    "-n": {"type": "boolean"},
+                    "-i": {"type": "boolean"},
+                    "head_limit": {"type": "number"},
+                    "offset": {"type": "number"},
+                    "multiline": {"type": "boolean"},
+                },
+                "required": ["pattern"],
+            },
+            "is_read_only": True,
+            "is_concurrency_safe": True,
+        },
+        "glob": {
+            "name": "glob",
+            "description": "Find workspace files by glob pattern with ripgrep.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "pattern": {"type": "string"},
+                    "path": {"type": "string"},
+                    "head_limit": {"type": "number"},
+                    "offset": {"type": "number"},
+                },
+                "required": ["pattern"],
+            },
+            "is_read_only": True,
+            "is_concurrency_safe": True,
+        },
+        "Bash": {
+            "name": "Bash",
+            "description": (
+                "Execute an allow-listed command in the workspace. "
+                + (
+                    "argv is preferred; shell strings are enabled for pipes and globs."
+                    if allow_shell
+                    else "Shell-string mode is disabled; use argv."
+                )
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "argv": {"type": "array", "items": {"type": "string"}},
+                    "command": {"type": "string"},
+                    "timeoutMs": {"type": "number"},
+                    "cwd": {"type": "string"},
+                    "run_in_background": {"type": "boolean"},
+                },
+            },
+            "is_read_only": exec_is_read_only,
+            "is_concurrency_safe": exec_is_read_only,
+        },
+        "web_fetch": {
+            "name": "web_fetch",
+            "description": (
+                "Fetch an HTTPS URL and return readable content. HTTP is upgraded to HTTPS; "
+                "results are cached by URL and prompt."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "url": {"type": "string"},
+                    "prompt": {"type": "string"},
+                    "max_chars": {"type": "number"},
+                },
+                "required": ["url"],
+            },
+            "is_read_only": True,
+            "is_concurrency_safe": True,
+        },
+    }

semora_coding-0.2.0/src/semora_coding/builtins/_exec.py

@@ -0,0 +1,303 @@
+"""Sandboxed command execution built-in."""
+
+from __future__ import annotations
+
+import re
+import shlex
+from collections.abc import Mapping
+
+from semora.workspace import SandboxCommand, ToolContext, WorkspaceViolation
+
+from ._types import (
+    BuiltinToolState,
+    ExecToolOptions,
+    ToolResult,
+    error_result,
+    require_workspace,
+    text_result,
+    tool_environment,
+)
+
+MAX_OUTPUT_BYTES = 256 * 1024
+MAX_PERSIST_BYTES = 16 * 1024 * 1024
+MAX_TIMEOUT_MS = 600_000
+
+SHELL_INTERPRETERS = frozenset(
+    {
+        "bash",
+        "sh",
+        "zsh",
+        "dash",
+        "ksh",
+        "tcsh",
+        "csh",
+        "fish",
+        "ash",
+        "busybox",
+        "python",
+        "ruby",
+        "perl",
+        "node",
+        "nodejs",
+        "deno",
+        "bun",
+        "php",
+        "lua",
+        "awk",
+        "gawk",
+        "mawk",
+        "nawk",
+        "sed",
+        "find",
+        "xargs",
+        "tar",
+        "cpio",
+        "zip",
+        "unzip",
+        "git",
+        "hg",
+        "svn",
+        "wget",
+        "curl",
+        "scp",
+        "rsync",
+        "ssh",
+        "sshpass",
+        "telnet",
+        "nc",
+        "ncat",
+        "socat",
+        "env",
+        "sudo",
+        "doas",
+        "su",
+        "docker",
+        "podman",
+        "kubectl",
+        "nsenter",
+        "chroot",
+        "unshare",
+        "setsid",
+    }
+)
+
+
+async def exec_tool(
+    call_id: str,
+    arguments: object,
+    context: ToolContext,
+    state: BuiltinToolState,
+    options: ExecToolOptions,
+) -> ToolResult:
+    """Execute through ``WorkspaceSession.run``, porting ``createExecTool().execute``."""
+    del state
+    params = arguments if isinstance(arguments, dict) else {}
+    if params.get("run_in_background") is True:
+        return error_result(
+            "run_in_background needs a background-task registry (not supported by this tool bundle)"
+        )
+    workspace = require_workspace(context)
+    if workspace is None:
+        return error_result("Bash requires an active workspace")
+
+    resolved = _resolve_command(params, options)
+    if isinstance(resolved, str):
+        return error_result(resolved)
+    argv, label = resolved
+
+    raw_cwd = params.get("cwd")
+    cwd = raw_cwd.strip() if isinstance(raw_cwd, str) and raw_cwd.strip() else "."
+    try:
+        resolved_cwd = await workspace.resolve(cwd, access="read")
+    except (OSError, ValueError, WorkspaceViolation) as error:
+        return error_result(f'cwd "{cwd}" is not inside the workspace: {error}')
+
+    timeout_ms = _timeout_ms(params.get("timeoutMs"), options.default_timeout_ms)
+    try:
+        result = await workspace.run(
+            SandboxCommand(
+                argv=argv,
+                cwd=str(resolved_cwd.path),
+                env=tool_environment(options.env_allow_list),
+                inherit_env=False,
+                timeout_seconds=timeout_ms / 1000,
+                require_isolation=options.require_isolation,
+                allowed_domains=options.allowed_domains,
+            )
+        )
+    except (OSError, ValueError, WorkspaceViolation) as error:
+        return error_result(f"sandboxed exec failed: {error}")
+
+    combined = result.stdout + (f"\n[stderr]\n{result.stderr}" if result.stderr else "")
+    encoded = combined.encode()
+    persisted_path: str | None = None
+    if len(encoded) > MAX_OUTPUT_BYTES:
+        safe_id = re.sub(r"[^A-Za-z0-9_-]", "_", call_id)[:64] or "out"
+        persisted_path = f".exec-output-{safe_id}.log"
+        try:
+            await workspace.fs.write_file(
+                persisted_path, encoded[:MAX_PERSIST_BYTES], atomic=True
+            )
+        except (OSError, ValueError, WorkspaceViolation):
+            persisted_path = None
+    text = _utf8_prefix(encoded, MAX_OUTPUT_BYTES) or "(no output)"
+    if persisted_path is not None:
+        text += (
+            f"\n\n[full output ({min(len(encoded), MAX_PERSIST_BYTES)} bytes) written to "
+            f"{persisted_path} — read this file for the complete output]"
+        )
+    elif len(encoded) > MAX_OUTPUT_BYTES:
+        text += f"\n\n[Output truncated at {MAX_OUTPUT_BYTES} bytes]"
+
+    if result.timed_out:
+        status = "timeout"
+        text += f"\n\n[Killed: timeout after {timeout_ms}ms]"
+    elif result.aborted:
+        status = "aborted"
+        text += "\n\n[Aborted by caller]"
+    elif result.signal:
+        status = f"signal {result.signal}"
+        text += f"\n\n[Killed by signal: {result.signal}]"
+    elif result.exit_code == 0:
+        status = "ok"
+    else:
+        status = f"exit {result.exit_code if result.exit_code is not None else 'unknown'}"
+    return text_result(text if status == "ok" else f"[{status}] {label}\n{text}")
+
+
+def _resolve_command(
+    params: Mapping[str, object], options: ExecToolOptions
+) -> tuple[list[str], str] | str:
+    argv_value = params.get("argv")
+    allow = frozenset(options.allow_list)
+    allow_all = "*" in allow
+    if isinstance(argv_value, list) and argv_value:
+        if not all(isinstance(item, str) for item in argv_value):
+            return "argv must be an array of strings"
+        argv = [str(item) for item in argv_value]
+        error = _validate_program(argv[0])
+        if error is not None:
+            return error
+        if not allow:
+            return (
+                "Bash is unconfigured: ExecToolOptions requires a non-empty allow_list. "
+                "Pass explicit command names to enable them."
+            )
+        if not allow_all and argv[0] not in allow:
+            return f'Executable "{argv[0]}" not in allow_list. Allowed: {", ".join(sorted(allow))}'
+        if not options.allow_shell and _is_interpreter(argv[0]):
+            return (
+                f'Executable "{argv[0]}" is a shell/interpreter/exec-surface and is blocked. '
+                "Set allow_shell=True only when an OS sandbox is the real boundary."
+            )
+        return argv, " ".join(argv)
+
+    command = params.get("command")
+    if isinstance(command, str) and command.strip():
+        if not options.allow_shell:
+            return 'Shell-string mode is disabled. Use { argv: ["program", "arg1", ...] } instead.'
+        if not allow:
+            return (
+                "Bash is unconfigured: ExecToolOptions requires a non-empty allow_list. "
+                "Pass explicit command names to enable them."
+            )
+        if not allow_all:
+            programs = _shell_programs(command)
+            if programs is None:
+                return (
+                    "Shell command could not be verified against the allow_list. "
+                    "Use argv form or a simpler command."
+                )
+            offending = sorted(set(programs) - allow)
+            if offending:
+                return (
+                    f"Command(s) not in allow_list: {', '.join(offending)}. "
+                    f"Allowed: {', '.join(sorted(allow))}"
+                )
+        return ["bash", "-lc", command], command
+    return "Either argv (preferred) or command must be provided"
+
+
+def _validate_program(program: str) -> str | None:
+    if not program:
+        return "program is empty"
+    if "/" in program or "\\" in program:
+        return f'program "{program}" must be a bare command name (no path separators)'
+    if ".." in program:
+        return f'program "{program}" must not contain ".."'
+    if program.startswith("-"):
+        return f'program "{program}" must not start with "-"'
+    return None
+
+
+def _is_interpreter(program: str) -> bool:
+    canonical = re.sub(
+        r"^(python|ruby|perl|node|lua|php)(?:-|)(?:\d+(?:\.\d+)?)$", r"\1", program
+    )
+    if canonical == "nodejs":
+        canonical = "node"
+    return canonical in SHELL_INTERPRETERS
+
+
+def _shell_programs(command: str) -> list[str] | None:
+    """Conservatively parse simple shell pipelines for per-command allow-list checks."""
+    if any(marker in command for marker in ("$", "`", "\n", "\r", "<", ">", "(", ")")):
+        return None
+    try:
+        lexer = shlex.shlex(command, posix=True, punctuation_chars="|&;")
+        lexer.whitespace_split = True
+        tokens = list(lexer)
+    except ValueError:
+        return None
+    programs: list[str] = []
+    expecting = True
+    for token in tokens:
+        if token in {"|", "||", "&&", ";", "&"}:
+            if expecting:
+                return None
+            expecting = True
+            continue
+        if expecting and "=" in token and not token.startswith("="):
+            continue
+        if expecting:
+            if _validate_program(token) is not None:
+                return None
+            programs.append(token)
+            expecting = False
+    return None if expecting or not programs else programs
+
+
+def _timeout_ms(value: object, default: int) -> int:
+    selected = (
+        int(value)
+        if isinstance(value, (int, float)) and not isinstance(value, bool)
+        else default
+    )
+    return min(max(selected, 1_000), MAX_TIMEOUT_MS)
+
+
+def _utf8_prefix(value: bytes, limit: int) -> str:
+    return value[:limit].decode("utf-8", errors="ignore")
+
+
+def exec_is_read_only(arguments: object) -> bool:
+    """Fail-closed concurrency classification from TS ``classifyReadOnly``."""
+    if not isinstance(arguments, dict) or arguments.get("run_in_background") is True:
+        return False
+    argv = arguments.get("argv")
+    if not isinstance(argv, list) or not argv or not all(isinstance(item, str) for item in argv):
+        return False
+    return argv[0] in {
+        "cat",
+        "head",
+        "tail",
+        "wc",
+        "pwd",
+        "ls",
+        "rg",
+        "grep",
+        "find",
+        "stat",
+        "file",
+        "diff",
+    }