symphony-code 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,11 @@
1
+ """Session artifacts: the images, html, csv and json a run produces, stored and versioned."""
2
+
3
+ from coding_agent.addons.artifacts.addon import ARTIFACT_CREATED, ARTIFACT_UPDATED, ArtifactsAddon
4
+ from coding_agent.addons.artifacts.capture import ArtifactError, Snapshot, snapshot_path
5
+ from coding_agent.addons.artifacts.kinds import ArtifactKind
6
+ from coding_agent.addons.artifacts.store import ArtifactStore, Manifest, Saved
7
+
8
+ __all__ = [
9
+ "ARTIFACT_CREATED", "ARTIFACT_UPDATED", "ArtifactError", "ArtifactKind", "ArtifactStore",
10
+ "ArtifactsAddon", "Manifest", "Saved", "Snapshot", "snapshot_path",
11
+ ]
@@ -0,0 +1,153 @@
1
+ """Capture the images, html, csv and json files a run produces as artifacts.
2
+
3
+ ``on_tool`` sees every successful tool call after it ran:
4
+
5
+ - ``write_file``, ``patch`` and ``generate_image`` capture the written path
6
+ when its suffix is html, csv, json or an image (see ``capture``). A file
7
+ inside a website folder (one below the workspace with ``index.html``)
8
+ versions that whole site instead. Manifests, configs, lockfiles and
9
+ anything under node_modules, .git, dist or build are skipped (``noise``),
10
+ as is a patch to an html or json file git tracks outside a website folder.
11
+ - ``save_artifact`` captures its path with the kind and title it was given.
12
+ - Any other tool except ``read_file`` captures the inline images it returned.
13
+
14
+ Each stored version is emitted through the session's harness as
15
+ ``artifact_created`` or ``artifact_updated`` (the manifest plus the absolute
16
+ ``path`` of its entry file), so it is journaled and reaches every host.
17
+ Unchanged content stores and emits nothing. Subagents inherit the add-on and
18
+ store into the parent session.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import asyncio
24
+ import logging
25
+ from collections.abc import Iterator, Mapping
26
+ from pathlib import Path
27
+ from typing import Any, Optional
28
+
29
+ from core_ai.content import normalize_content
30
+ from core_harness import Addon, CoreHarness
31
+ from core_harness.models import ToolCall, ToolResult
32
+
33
+ from coding_agent.addons.artifacts.capture import (
34
+ SITE_ENTRY,
35
+ ArtifactError,
36
+ Snapshot,
37
+ snapshot_image_part,
38
+ snapshot_path,
39
+ snapshot_site,
40
+ )
41
+ from coding_agent.addons.artifacts.kinds import ArtifactKind, kind_of
42
+ from coding_agent.addons.artifacts.noise import git_tracked, is_noise
43
+ from coding_agent.addons.artifacts.store import ArtifactStore, Saved
44
+
45
+ ARTIFACT_CREATED = "artifact_created"
46
+ ARTIFACT_UPDATED = "artifact_updated"
47
+ PATH_TOOLS = frozenset({"write_file", "patch", "generate_image"})
48
+ SAVE_TOOL = "save_artifact"
49
+ PATCH_TOOL = "patch"
50
+ TRACKED_SOURCE_KINDS = frozenset({ArtifactKind.HTML, ArtifactKind.JSON})
51
+ # Reading an image shows an existing file; it produces nothing.
52
+ READ_TOOLS = frozenset({"read_file"})
53
+
54
+ logger = logging.getLogger(__name__)
55
+
56
+
57
+ def resolve(workspace: Path, raw: str) -> Path:
58
+ """The path a workspace tool wrote, resolved the way ``WorkspaceTool`` does."""
59
+ candidate = Path(raw.strip()).expanduser()
60
+ return (candidate if candidate.is_absolute() else workspace / candidate).resolve()
61
+
62
+
63
+ def site_of(path: Path, workspace: Path) -> Path | None:
64
+ """The nearest folder below the workspace holding ``index.html`` and ``path``.
65
+
66
+ Writing any file of a website (its index.html, css, scripts or images)
67
+ versions the whole site.
68
+ """
69
+ for folder in path.parents:
70
+ if folder == workspace or not folder.is_relative_to(workspace):
71
+ return None
72
+ if (folder / SITE_ENTRY).is_file():
73
+ return folder
74
+ return None
75
+
76
+
77
+ def artifact_frame(store: ArtifactStore, session_id: str, saved: Saved) -> tuple[str, dict[str, object]]:
78
+ manifest = saved.manifest
79
+ entry = store.folder(session_id, manifest.id) / manifest.entry
80
+ return (
81
+ ARTIFACT_CREATED if saved.created else ARTIFACT_UPDATED,
82
+ {**manifest.to_json(), "path": str(entry)},
83
+ )
84
+
85
+
86
+ class ArtifactsAddon(Addon):
87
+ name = "artifacts"
88
+
89
+ def __init__(self, store: ArtifactStore, workspace: Path, owner: Optional[CoreHarness] = None) -> None:
90
+ self.store = store
91
+ self.workspace = Path(workspace).expanduser().resolve()
92
+ # The harness whose session keeps the artifacts: the parent for subagents.
93
+ self.owner = owner
94
+
95
+ def attach(self, harness: Any) -> None:
96
+ if self.owner is None and isinstance(harness, CoreHarness):
97
+ self.owner = harness
98
+
99
+ def fork_for_child(self, parent_harness: Any) -> Optional[Addon]:
100
+ del parent_harness
101
+ return ArtifactsAddon(self.store, self.workspace, self.owner)
102
+
103
+ @staticmethod
104
+ def tracked_edit(tool_name: str, kind: ArtifactKind, path: Path) -> bool:
105
+ """A patch to a git-tracked html or json file edits source, not output."""
106
+ return tool_name == PATCH_TOOL and kind in TRACKED_SOURCE_KINDS and git_tracked(path)
107
+
108
+ def snapshots(self, tool_call: ToolCall, result: ToolResult) -> Iterator[Snapshot]:
109
+ arguments: Mapping[str, Any] = tool_call.arguments
110
+ raw = arguments.get("path")
111
+ if tool_call.name == SAVE_TOOL and isinstance(raw, str):
112
+ title = arguments.get("title")
113
+ yield snapshot_path(
114
+ resolve(self.workspace, raw), self.workspace,
115
+ ArtifactKind(str(arguments.get("kind"))), title if isinstance(title, str) else "",
116
+ )
117
+ elif tool_call.name in PATH_TOOLS and isinstance(raw, str):
118
+ path = resolve(self.workspace, raw)
119
+ if is_noise(path, self.workspace):
120
+ return
121
+ site = site_of(path, self.workspace)
122
+ kind = kind_of(path)
123
+ if site is not None:
124
+ yield snapshot_site(site, self.workspace)
125
+ elif kind is not None and not self.tracked_edit(tool_call.name, kind, path):
126
+ yield snapshot_path(path, self.workspace)
127
+ elif tool_call.name not in READ_TOOLS and not isinstance(result.content, str):
128
+ for index, part in enumerate(normalize_content(result.content)):
129
+ captured = snapshot_image_part(part, tool_call.id, index)
130
+ if captured is not None:
131
+ yield captured
132
+
133
+ async def on_tool(self, **payload: Any) -> None:
134
+ tool_call, result, owner = payload.get("tool_call"), payload.get("result"), self.owner
135
+ if not isinstance(tool_call, ToolCall) or not isinstance(result, ToolResult) or owner is None:
136
+ return
137
+ if result.status != "success" or not owner.session_id:
138
+ return
139
+ session_id = owner.session_id
140
+ try:
141
+ # Reading files and asking git happen off the event loop.
142
+ captures = await asyncio.to_thread(lambda: list(self.snapshots(tool_call, result)))
143
+ for captured in captures:
144
+ saved = await asyncio.to_thread(self.store.save, session_id, captured, tool_call.id)
145
+ if saved is not None:
146
+ event, body = artifact_frame(self.store, session_id, saved)
147
+ await owner.emit(event, body)
148
+ except (ArtifactError, OSError, ValueError) as exc:
149
+ # A file that cannot be kept must not fail the run that wrote it.
150
+ logger.warning("artifact capture skipped for %s: %s", tool_call.name, exc)
151
+
152
+
153
+ __all__ = ["ARTIFACT_CREATED", "ARTIFACT_UPDATED", "ArtifactsAddon", "artifact_frame", "resolve", "site_of"]
@@ -0,0 +1,169 @@
1
+ """Turn a written path or an image result part into an artifact snapshot.
2
+
3
+ A snapshot is the complete content of one artifact version: its kind, a
4
+ stable source (the workspace path it came from), the entry file and every
5
+ file's bytes. ``ArtifactStore`` versions snapshots by sha256.
6
+
7
+ - An image (png/jpg/jpeg/webp/gif/svg), a ``.csv`` or a ``.json`` file is a
8
+ single-file artifact. CSV must be UTF-8 and JSON must parse.
9
+ - A ``.html`` file is a single-file html artifact, except ``index.html`` in a
10
+ folder below the workspace, which captures that whole folder (the site and
11
+ its assets) with ``index.html`` as the entry.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import base64
17
+ import binascii
18
+ import json
19
+ from collections.abc import Mapping
20
+ from dataclasses import dataclass
21
+ from pathlib import Path
22
+
23
+ from core_ai.content import sniff_image_media_type
24
+
25
+ from coding_agent.addons.artifacts.kinds import IMAGE_MIME_TYPES, TEXT_MIME_TYPES, ArtifactKind, kind_of
26
+
27
+ MAX_FILE_BYTES = 20 * 1024 * 1024
28
+ MAX_SITE_FILES = 200
29
+ MAX_SITE_BYTES = 20 * 1024 * 1024
30
+ SKIPPED_DIRS = frozenset({"node_modules", "__pycache__"})
31
+ SITE_ENTRY = "index.html"
32
+
33
+
34
+ class ArtifactError(ValueError):
35
+ """The path cannot become an artifact of the requested kind."""
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class Snapshot:
40
+ kind: ArtifactKind
41
+ source: str
42
+ title: str
43
+ entry: str
44
+ mime: str
45
+ files: tuple[tuple[str, bytes], ...]
46
+
47
+
48
+ def display_source(path: Path, workspace: Path) -> str:
49
+ """The path relative to the workspace when inside it, else absolute."""
50
+ return path.relative_to(workspace).as_posix() if path.is_relative_to(workspace) else str(path)
51
+
52
+
53
+ def _read(path: Path) -> bytes:
54
+ if path.is_symlink() or not path.is_file():
55
+ raise ArtifactError(f"not a regular file: {path}")
56
+ if path.stat().st_size > MAX_FILE_BYTES:
57
+ raise ArtifactError(f"file is over {MAX_FILE_BYTES // (1024 * 1024)} MiB: {path}")
58
+ return path.read_bytes()
59
+
60
+
61
+ def image_mime(payload: bytes, name: str) -> str:
62
+ """png/jpg/jpeg/webp/gif/svg by suffix, else by magic bytes."""
63
+ suffix = Path(name).suffix.lower()
64
+ if suffix in IMAGE_MIME_TYPES:
65
+ return IMAGE_MIME_TYPES[suffix]
66
+ sniffed = sniff_image_media_type(payload)
67
+ if sniffed not in IMAGE_MIME_TYPES.values():
68
+ raise ArtifactError(f"not a png, jpeg, webp, gif or svg image: {name}")
69
+ return sniffed
70
+
71
+
72
+ def _check_text(kind: ArtifactKind, payload: bytes, name: str) -> None:
73
+ try:
74
+ text = payload.decode("utf-8")
75
+ if kind is ArtifactKind.JSON:
76
+ json.loads(text)
77
+ except (UnicodeDecodeError, ValueError) as exc:
78
+ raise ArtifactError(f"{name} is not valid {kind.value}: {exc}") from exc
79
+
80
+
81
+ def _site_files(folder: Path) -> tuple[tuple[str, bytes], ...]:
82
+ files: list[tuple[str, bytes]] = []
83
+ total = 0
84
+ for path in sorted(folder.rglob("*")):
85
+ relative = path.relative_to(folder)
86
+ if any(part.startswith(".") or part in SKIPPED_DIRS for part in relative.parts):
87
+ continue
88
+ if path.is_symlink() or not path.is_file():
89
+ continue
90
+ payload = _read(path)
91
+ total += len(payload)
92
+ files.append((relative.as_posix(), payload))
93
+ if len(files) > MAX_SITE_FILES or total > MAX_SITE_BYTES:
94
+ raise ArtifactError(f"site folder is too large to keep as an artifact: {folder}")
95
+ return tuple(files)
96
+
97
+
98
+ def snapshot_site(folder: Path, workspace: Path, title: str = "") -> Snapshot:
99
+ """A website folder whose entry is ``index.html``."""
100
+ if not (folder / SITE_ENTRY).is_file():
101
+ raise ArtifactError(f"a website folder needs {SITE_ENTRY}: {folder}")
102
+ return Snapshot(
103
+ kind=ArtifactKind.HTML,
104
+ source=display_source(folder, workspace),
105
+ title=title or folder.name,
106
+ entry=SITE_ENTRY,
107
+ mime=TEXT_MIME_TYPES[ArtifactKind.HTML],
108
+ files=_site_files(folder),
109
+ )
110
+
111
+
112
+ def snapshot_path(path: Path, workspace: Path, kind: ArtifactKind | None = None, title: str = "") -> Snapshot:
113
+ """Snapshot a written file or folder; ``kind`` defaults to the suffix's kind."""
114
+ if path.is_dir() and not path.is_symlink():
115
+ if kind not in (None, ArtifactKind.HTML):
116
+ raise ArtifactError(f"only an html artifact can be a folder: {path}")
117
+ return snapshot_site(path, workspace, title)
118
+ chosen = kind or kind_of(path)
119
+ if chosen is None:
120
+ raise ArtifactError(f"not an html, csv, json or image file: {path}")
121
+ if chosen is ArtifactKind.HTML and path.name == SITE_ENTRY and path.parent != workspace:
122
+ return snapshot_site(path.parent, workspace, title)
123
+ payload = _read(path)
124
+ if chosen is ArtifactKind.IMAGE:
125
+ mime = image_mime(payload, path.name)
126
+ else:
127
+ _check_text(chosen, payload, path.name)
128
+ mime = TEXT_MIME_TYPES[chosen]
129
+ return Snapshot(
130
+ kind=chosen,
131
+ source=display_source(path, workspace),
132
+ title=title or path.name,
133
+ entry=path.name,
134
+ mime=mime,
135
+ files=((path.name, payload),),
136
+ )
137
+
138
+
139
+ def snapshot_image_part(part: Mapping[str, object], call_id: str, index: int) -> Snapshot | None:
140
+ """An inline image a tool returned without writing a file."""
141
+ data = part.get("data")
142
+ if part.get("type") != "image" or not isinstance(data, str):
143
+ return None
144
+ try:
145
+ payload = base64.b64decode(data, validate=True)
146
+ except (binascii.Error, ValueError):
147
+ return None
148
+ filename = part.get("filename")
149
+ name = Path(filename).name if isinstance(filename, str) and Path(filename).name else f"image-{index + 1}"
150
+ try:
151
+ mime = image_mime(payload, name)
152
+ except ArtifactError:
153
+ return None
154
+ suffix = next(key for key, value in IMAGE_MIME_TYPES.items() if value == mime)
155
+ entry = name if Path(name).suffix.lower() in IMAGE_MIME_TYPES else f"{name}{suffix}"
156
+ return Snapshot(
157
+ kind=ArtifactKind.IMAGE,
158
+ source=f"{call_id}#image-{index + 1}",
159
+ title=name,
160
+ entry=entry,
161
+ mime=mime,
162
+ files=((entry, payload),),
163
+ )
164
+
165
+
166
+ __all__ = [
167
+ "ArtifactError", "MAX_FILE_BYTES", "MAX_SITE_BYTES", "MAX_SITE_FILES", "SITE_ENTRY", "Snapshot",
168
+ "display_source", "image_mime", "snapshot_image_part", "snapshot_path", "snapshot_site",
169
+ ]
@@ -0,0 +1,51 @@
1
+ """The four artifact kinds and the file suffixes that map to them."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from enum import StrEnum
6
+ from pathlib import Path
7
+
8
+
9
+ class ArtifactKind(StrEnum):
10
+ """What an artifact holds. Hosts pick a preview from this."""
11
+
12
+ HTML = "html"
13
+ CSV = "csv"
14
+ JSON = "json"
15
+ IMAGE = "image"
16
+
17
+
18
+ IMAGE_MIME_TYPES = {
19
+ ".png": "image/png",
20
+ ".jpg": "image/jpeg",
21
+ ".jpeg": "image/jpeg",
22
+ ".webp": "image/webp",
23
+ ".gif": "image/gif",
24
+ ".svg": "image/svg+xml",
25
+ }
26
+ TEXT_MIME_TYPES = {
27
+ ArtifactKind.HTML: "text/html",
28
+ ArtifactKind.CSV: "text/csv",
29
+ ArtifactKind.JSON: "application/json",
30
+ }
31
+ SUFFIX_KINDS = {
32
+ ".html": ArtifactKind.HTML,
33
+ ".csv": ArtifactKind.CSV,
34
+ ".json": ArtifactKind.JSON,
35
+ **{suffix: ArtifactKind.IMAGE for suffix in IMAGE_MIME_TYPES},
36
+ }
37
+
38
+
39
+ def kind_of(path: Path) -> ArtifactKind | None:
40
+ """The kind auto-capture assigns to ``path``, or ``None`` for other files."""
41
+ return SUFFIX_KINDS.get(path.suffix.lower())
42
+
43
+
44
+ def mime_of(kind: ArtifactKind, entry: Path) -> str:
45
+ """The entry file's media type. An image without a known suffix is generic."""
46
+ if kind is ArtifactKind.IMAGE:
47
+ return IMAGE_MIME_TYPES.get(entry.suffix.lower(), "application/octet-stream")
48
+ return TEXT_MIME_TYPES[kind]
49
+
50
+
51
+ __all__ = ["IMAGE_MIME_TYPES", "SUFFIX_KINDS", "TEXT_MIME_TYPES", "ArtifactKind", "kind_of", "mime_of"]
@@ -0,0 +1,48 @@
1
+ """Files that match an artifact suffix but are project plumbing, not output.
2
+
3
+ Auto-capture skips them; ``save_artifact`` still keeps any of them on request.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import fnmatch
9
+ import subprocess
10
+ from pathlib import Path
11
+
12
+ # Any path through one of these folders is dependencies, VCS data or build output.
13
+ NOISE_DIRS = frozenset({"node_modules", ".git", "dist", "build"})
14
+ MANIFEST_NAMES = frozenset({"package.json", "package-lock.json", "npm-shrinkwrap.json"})
15
+ CONFIG_PATTERNS = ("tsconfig*.json", "*.config.json")
16
+ # Lockfiles of every package manager: yarn.lock, Cargo.lock, uv.lock,
17
+ # pnpm-lock.yaml, bun.lock(b), deno.lock, *.lock.json, ...
18
+ LOCK_PATTERNS = ("*.lock", "*.lockb", "*-lock.json", "*-lock.yaml", "*.lock.json", "*-lock.yml")
19
+ GIT_TIMEOUT_SECONDS = 5
20
+
21
+
22
+ def is_noise(path: Path, workspace: Path) -> bool:
23
+ """A manifest, config or lockfile, or anything under a noise folder."""
24
+ parts = path.relative_to(workspace).parts if path.is_relative_to(workspace) else path.parts
25
+ if any(part in NOISE_DIRS for part in parts[:-1]):
26
+ return True
27
+ name = path.name.lower()
28
+ if name in MANIFEST_NAMES:
29
+ return True
30
+ return any(fnmatch.fnmatchcase(name, pattern) for pattern in (*CONFIG_PATTERNS, *LOCK_PATTERNS))
31
+
32
+
33
+ def git_tracked(path: Path) -> bool:
34
+ """Whether git tracks ``path`` in the repository that contains it."""
35
+ try:
36
+ result = subprocess.run(
37
+ ["git", "-C", str(path.parent), "ls-files", "--error-unmatch", "--", path.name],
38
+ capture_output=True,
39
+ timeout=GIT_TIMEOUT_SECONDS,
40
+ check=False,
41
+ )
42
+ except (OSError, subprocess.TimeoutExpired):
43
+ # No git, or a hung repository: nothing proves the file is tracked.
44
+ return False
45
+ return result.returncode == 0
46
+
47
+
48
+ __all__ = ["NOISE_DIRS", "git_tracked", "is_noise"]
@@ -0,0 +1,212 @@
1
+ """Versioned artifact files under ``<session dir>/artifacts``.
2
+
3
+ Layout, per session::
4
+
5
+ artifacts/index.json every artifact's latest manifest
6
+ artifacts/<artifact_id>/manifest.json the latest version's manifest
7
+ artifacts/<artifact_id>/v<N>/... the files of version N
8
+
9
+ A version directory is staged under a temporary name and renamed into place,
10
+ and both JSON files are published with a temporary file plus rename, so a
11
+ reader never sees a partial artifact. The id is derived from the kind and the
12
+ source path, so later writes of the same file or site are versions of one
13
+ artifact. A snapshot whose sha256 matches the latest version stores nothing.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import hashlib
19
+ import json
20
+ import re
21
+ import shutil
22
+ import threading
23
+ import uuid
24
+ from dataclasses import asdict, dataclass
25
+ from datetime import datetime, timezone
26
+ from pathlib import Path
27
+
28
+ from coding_agent.addons.artifacts.capture import Snapshot
29
+ from coding_agent.addons.artifacts.kinds import ArtifactKind
30
+ from coding_agent.addons.persistence.artifacts import safe_path, snapshot
31
+
32
+ SESSION_ID = re.compile(r"^[A-Za-z0-9._-]+$")
33
+ ARTIFACT_ID = re.compile(r"^[0-9a-f]{16}$")
34
+ INDEX = "index.json"
35
+ MANIFEST = "manifest.json"
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class Manifest:
40
+ """One artifact's latest version. ``entry`` is relative to the artifact folder."""
41
+
42
+ id: str
43
+ kind: ArtifactKind
44
+ title: str
45
+ created_at: str
46
+ updated_at: str
47
+ version: int
48
+ tool_call_id: str
49
+ source: str
50
+ entry: str
51
+ mime: str
52
+ sha256: str
53
+ size: int
54
+
55
+ def to_json(self) -> dict[str, object]:
56
+ return {**asdict(self), "kind": self.kind.value}
57
+
58
+ @classmethod
59
+ def from_json(cls, data: dict[str, object]) -> Manifest:
60
+ def text(key: str) -> str:
61
+ value = data.get(key)
62
+ if not isinstance(value, str):
63
+ raise ValueError(f"artifact manifest field {key!r} must be a string")
64
+ return value
65
+
66
+ def number(key: str) -> int:
67
+ value = data.get(key)
68
+ if not isinstance(value, int) or isinstance(value, bool):
69
+ raise ValueError(f"artifact manifest field {key!r} must be an integer")
70
+ return value
71
+
72
+ return cls(
73
+ id=text("id"), kind=ArtifactKind(text("kind")), title=text("title"),
74
+ created_at=text("created_at"), updated_at=text("updated_at"), version=number("version"),
75
+ tool_call_id=text("tool_call_id"), source=text("source"), entry=text("entry"),
76
+ mime=text("mime"), sha256=text("sha256"), size=number("size"),
77
+ )
78
+
79
+
80
+ @dataclass(frozen=True)
81
+ class Saved:
82
+ """A stored version. ``created`` is false when it updated an existing artifact."""
83
+
84
+ manifest: Manifest
85
+ created: bool
86
+
87
+
88
+ def artifact_id(kind: ArtifactKind, source: str) -> str:
89
+ return hashlib.sha256(f"{kind.value}:{source}".encode()).hexdigest()[:16]
90
+
91
+
92
+ def content_digest(files: tuple[tuple[str, bytes], ...]) -> str:
93
+ """sha256 of one file's bytes, or of a folder's sorted (path, file sha256) list."""
94
+ if len(files) == 1:
95
+ return hashlib.sha256(files[0][1]).hexdigest()
96
+ listing = "".join(f"{name}\0{hashlib.sha256(payload).hexdigest()}\n" for name, payload in sorted(files))
97
+ return hashlib.sha256(listing.encode()).hexdigest()
98
+
99
+
100
+ def _now() -> str:
101
+ return datetime.now(timezone.utc).isoformat(timespec="seconds")
102
+
103
+
104
+ def _read_json(path: Path) -> dict[str, object] | None:
105
+ try:
106
+ data = json.loads(path.read_text(encoding="utf-8"))
107
+ except FileNotFoundError:
108
+ return None
109
+ if not isinstance(data, dict):
110
+ raise ValueError(f"not a JSON object: {path}")
111
+ return data
112
+
113
+
114
+ class ArtifactStore:
115
+ """Artifacts of the sessions under one sessions directory."""
116
+
117
+ def __init__(self, sessions_root: Path) -> None:
118
+ self.sessions_root = Path(sessions_root).expanduser().resolve()
119
+ self._lock = threading.Lock()
120
+
121
+ def directory(self, session_id: str) -> Path:
122
+ if session_id in {".", ".."} or not SESSION_ID.fullmatch(session_id):
123
+ raise ValueError(f"invalid session_id: {session_id!r}")
124
+ return safe_path(self.sessions_root, session_id, "artifacts")
125
+
126
+ def folder(self, session_id: str, artifact: str) -> Path:
127
+ if not ARTIFACT_ID.fullmatch(artifact):
128
+ raise ValueError(f"invalid artifact_id: {artifact!r}")
129
+ return safe_path(self.directory(session_id), artifact)
130
+
131
+ def save(self, session_id: str, captured: Snapshot, tool_call_id: str) -> Saved | None:
132
+ """Store ``captured`` as a new version; ``None`` when its content is unchanged."""
133
+ identifier = artifact_id(captured.kind, captured.source)
134
+ digest = content_digest(captured.files)
135
+ with self._lock:
136
+ folder = self.folder(session_id, identifier)
137
+ stored = _read_json(folder / MANIFEST)
138
+ previous = Manifest.from_json(stored) if stored is not None else None
139
+ if previous is not None and previous.sha256 == digest:
140
+ return None
141
+ version = previous.version + 1 if previous is not None else 1
142
+ self._write_version(folder, f"v{version}", captured.files)
143
+ now = _now()
144
+ manifest = Manifest(
145
+ id=identifier,
146
+ kind=captured.kind,
147
+ title=captured.title,
148
+ created_at=previous.created_at if previous is not None else now,
149
+ updated_at=now,
150
+ version=version,
151
+ tool_call_id=tool_call_id,
152
+ source=captured.source,
153
+ entry=f"v{version}/{captured.entry}",
154
+ mime=captured.mime,
155
+ sha256=digest,
156
+ size=sum(len(payload) for _, payload in captured.files),
157
+ )
158
+ snapshot(folder / MANIFEST, manifest.to_json())
159
+ self._index(session_id, manifest)
160
+ return Saved(manifest=manifest, created=previous is None)
161
+
162
+ def _write_version(self, folder: Path, name: str, files: tuple[tuple[str, bytes], ...]) -> None:
163
+ folder.mkdir(parents=True, exist_ok=True)
164
+ staging = safe_path(folder, f".{name}.{uuid.uuid4().hex}.tmp")
165
+ try:
166
+ for relative, payload in files:
167
+ target = safe_path(staging, *relative.split("/"))
168
+ target.parent.mkdir(parents=True, exist_ok=True)
169
+ target.write_bytes(payload)
170
+ final = safe_path(folder, name)
171
+ if final.exists():
172
+ # Left by a save that crashed before its manifest was published.
173
+ shutil.rmtree(final)
174
+ staging.rename(final)
175
+ finally:
176
+ if staging.exists():
177
+ shutil.rmtree(staging)
178
+
179
+ def _index(self, session_id: str, manifest: Manifest) -> None:
180
+ rows = [row for row in self.manifests(session_id) if row.id != manifest.id]
181
+ rows.append(manifest)
182
+ snapshot(self.directory(session_id) / INDEX, {"artifacts": [row.to_json() for row in rows]})
183
+
184
+ def manifests(self, session_id: str) -> list[Manifest]:
185
+ """Every artifact of the session in creation order; empty before the first."""
186
+ data = _read_json(self.directory(session_id) / INDEX)
187
+ rows = data.get("artifacts") if data is not None else []
188
+ if not isinstance(rows, list):
189
+ raise ValueError("artifact index must hold a list")
190
+ return [Manifest.from_json(row) for row in rows if isinstance(row, dict)]
191
+
192
+ def get(self, session_id: str, artifact: str) -> Manifest:
193
+ stored = _read_json(self.folder(session_id, artifact) / MANIFEST)
194
+ if stored is None:
195
+ raise KeyError(f"unknown artifact: {artifact}")
196
+ return Manifest.from_json(stored)
197
+
198
+ def file(self, session_id: str, artifact: str, relative: str) -> Path:
199
+ """A stored file of the artifact; rejects traversal, links and folders."""
200
+ parts = [part for part in relative.split("/") if part]
201
+ path = safe_path(self.folder(session_id, artifact), *parts)
202
+ if not parts or not path.is_file():
203
+ raise KeyError(f"no such artifact file: {relative}")
204
+ return path
205
+
206
+ def files(self, session_id: str, manifest: Manifest) -> list[str]:
207
+ """The latest version's files, relative to its version folder."""
208
+ version = safe_path(self.folder(session_id, manifest.id), f"v{manifest.version}")
209
+ return sorted(path.relative_to(version).as_posix() for path in version.rglob("*") if path.is_file())
210
+
211
+
212
+ __all__ = ["ArtifactStore", "Manifest", "Saved", "artifact_id", "content_digest"]
coding_agent/agent.py CHANGED
@@ -43,6 +43,7 @@ from coding_agent.config import (
43
43
  ensure_spawn_settings,
44
44
  resolve_coding_agent_config,
45
45
  )
46
+ from coding_agent.addons.artifacts import ArtifactsAddon, ArtifactStore
46
47
  from coding_agent.addons.evaluation import JEV_SYSTEM_SEGMENT
47
48
  from coding_agent.addons.learning import LearningLoop, LearningStore
48
49
  from coding_agent.tools.memory import MemoryGetTool, MemorySearchTool, MemoryTool
@@ -217,6 +218,13 @@ class CodingAgent:
217
218
  self.workspace, self.sink, approvals=self.config.approvals, unattended=self.unattended
218
219
  )
219
220
  addons.append(self.approval)
221
+ # Artifacts live beside the session's transcript, so only a JSONL store keeps them.
222
+ self.artifacts: Optional[ArtifactsAddon] = (
223
+ ArtifactsAddon(ArtifactStore(self.persistence.root), self.workspace)
224
+ if isinstance(self.persistence, JsonlPersistence) else None
225
+ )
226
+ if self.artifacts is not None:
227
+ addons.append(self.artifacts)
220
228
  if self.config.skills.enabled:
221
229
  addons.append(SkillsAddon(str(self.workspace), self.skill_registry))
222
230
  self.harness = CoreHarness(
@@ -309,7 +317,8 @@ class CodingAgent:
309
317
  should_inject=self.config.learning.enabled,
310
318
  ))
311
319
  gate = self.approval.fork_for_child(parent)
312
- return addons + ([gate] if gate is not None else [])
320
+ artifacts = self.artifacts.fork_for_child(parent) if self.artifacts is not None else None
321
+ return addons + [addon for addon in (gate, artifacts) if addon is not None]
313
322
 
314
323
  async def run(
315
324
  self,