@pi-in-go/pigpen-session-ingest 0.1.0

package/CREDITS.md

@@ -0,0 +1,15 @@
+# Credits
+
+`extensions/session-ingest` is original work by **Michael Kinsy**, moved into
+Pigpen from the author's personal PiG configuration and released under Pigpen's
+MIT license (see [LICENSE](LICENSE)). It is not derived from another project.
+
+It reads the session file format documented by Pi
+(https://github.com/earendil-works/pi, MIT, Mario Zechner); it contains none of
+Pi's code.
+
+Changes made when it was moved: ported to PiG's public Go SDK; the `turn`,
+`tools` and `stats` modes, which the original advertised but did not implement,
+were written; output truncation was made rune-safe; the Next hint appears only
+when there is more to read; `query` searches the full text
+(`maxCharsPerItem` bounds the excerpts, not the search).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Kinsy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# session-ingest
+
+A Go extension for PiG that adds one tool, `read_session`. It lets the model (or
+you, by asking it) look inside a Pi or PiG session transcript (`.jsonl`) without
+pasting the whole file into the context window. Every mode caps its output at 50 KB /
+2000 lines and says how to fetch the next page or narrow the request. `toc`, `tools`
+and `stats` summarize; `turn` hides thinking and tool results unless `include` asks
+for them; `slice` and `query` show message text as recorded, tool results included
+(`maxCharsPerItem` shortens each item).
+
+```text
+read_session(path, mode = toc | query | slice | turn | tools | stats, ...)
+```
+
+| Mode | Answers | Output |
+|---|---|---|
+| `toc` (default) | What happened, turn by turn? | One row per user turn: time, request, tools used, errors, cost. |
+| `query` | Where was X discussed? | Ranked hits (`query`, `regex`, `caseSensitive`), each with turn, role, tool, excerpt and the call that fetches it. |
+| `slice` | Show messages N to M. | A page of normalized messages, optionally filtered by `roles`. |
+| `turn` | Show turn N in full. | The user message, assistant messages and tool activity of one turn. `include` picks `text`, `thinking`, `tool_calls`, `tool_results`, `errors`, `usage` (default: text, tool_calls, errors). |
+| `tools` | Which tools ran, on which files? | Calls, results and errors per tool, and the files touched by `read`, `write` and `edit` (`turn` restricts to one turn). |
+| `stats` | How big was it? | Turns, messages by role, tool calls, errors, tokens, cost, models, duration. |
+
+Common parameters: `start` and `limit` (paging), `maxCharsPerItem` (truncate long
+text, 0 = do not), `format` (`compact_markdown` by default, or `json`).
+
+Not covered: the tool reads every `message` entry in file order. It does not follow
+the session tree, so a forked session shows both branches in sequence; it ignores
+compaction and other non-message entries.
+
+## Install
+
+```sh
+pig install ./components/session-ingest
+```
+
+The extension builds from source on first use (Go toolchain required) or fuses into a
+Piglet Binary. It needs no network and no Node runtime. The tool can read any file
+path it is given, like PiG's own `read` tool, and returns text only.
+`pig package validate ./components/session-ingest` validates the Package.
+
+## Test
+
+The tests use PiG's public SDK through a fake host. From the Pigpen root:
+
+```sh
+PIG_BIN=/path/to/pig npm run test:go-ports -- -race
+```
+
+MIT. © Michael Kinsy. See [CREDITS.md](CREDITS.md).

package/extensions/session-ingest/bench_test.go

@@ -0,0 +1,68 @@
+package sessioningest
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// read_session parses the whole session file on every call (then slices, queries or tables it). A long session
+// is tens of MB of JSONL, mostly tool output.
+//
+//	go test -run xxx -bench . -benchmem
+func benchSession(b *testing.B, messages int) string {
+	b.Helper()
+	var s strings.Builder
+	s.WriteString(`{"type":"session","id":"0199abcd","version":3,"cwd":"/work/repo","timestamp":"2026-01-01T00:00:00Z"}` + "\n")
+	for i := 0; i < messages; i++ {
+		fmt.Fprintf(&s, `{"type":"message","id":"u%d","timestamp":"2026-01-01T00:00:%02dZ","message":{"role":"user","content":[{"type":"text","text":"please fix the failing test number %d"}]}}`+"\n", i, i%60, i)
+		fmt.Fprintf(&s, `{"type":"message","id":"a%d","timestamp":"2026-01-01T00:00:%02dZ","message":{"role":"assistant","content":[{"type":"text","text":"Looking at it now."},{"type":"toolCall","id":"c%d","name":"bash","arguments":{"command":"go test ./..."}}],"usage":{"input":1200,"output":80,"cacheRead":900,"cacheWrite":0,"totalTokens":2180,"cost":{"total":0.0123}}}}`+"\n", i, i%60, i)
+		fmt.Fprintf(&s, `{"type":"message","id":"t%d","timestamp":"2026-01-01T00:00:%02dZ","message":{"role":"toolResult","toolCallId":"c%d","toolName":"bash","content":[{"type":"text","text":%q}]}}`+"\n", i, i%60, i, strings.Repeat("ok  \tgithub.com/example/pkg\t0.123s\n", 20))
+	}
+	path := filepath.Join(b.TempDir(), "session.jsonl")
+	if err := os.WriteFile(path, []byte(s.String()), 0o600); err != nil {
+		b.Fatal(err)
+	}
+	return path
+}
+
+func BenchmarkParseSessionFile(b *testing.B) {
+	path := benchSession(b, 2000)
+	info, _ := os.Stat(path)
+	b.SetBytes(info.Size())
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		if _, err := parseSessionFile(path, 2000); err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+func BenchmarkBuildQueryReport(b *testing.B) {
+	session, err := parseSessionFile(benchSession(b, 2000), 2000)
+	if err != nil {
+		b.Fatal(err)
+	}
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		if _, err := buildQueryReport(session, "failing test", false, false, 0, 10, 300); err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+func BenchmarkBuildTOCReport(b *testing.B) {
+	session, err := parseSessionFile(benchSession(b, 2000), 2000)
+	if err != nil {
+		b.Fatal(err)
+	}
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		buildTOCReport(session, 0, 50)
+	}
+}