Merge dev into main

LICENSES/MIT-turtle-agent-before-agpl.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pjerra
+
+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.

NOTICE

@@ -1,6 +1,11 @@
 turtle-agent
 Copyright (c) 2026 pjerra
 
+turtle-agent is licensed under the GNU Affero General Public License v3.0 or later (see LICENSE).
+Versions before the licence change were MIT-licensed (LICENSES/MIT-turtle-agent-before-agpl.txt).
+The third-party code below stays under its own licence and is compatible with the AGPL.
+Contributions: one commit (af8a2fd, session create) by Sagiroth, relicensed with his consent (see the licence-change PR).
+
 turtle-agent contains code ported from agent-wow
 (https://github.com/agent-wow/agent-wow), commit 5ef4916, used under the MIT License:
 

cmd/turtle-agent/commander_gps.go

@@ -0,0 +1,68 @@
+package main
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	"github.com/pjerra/turtle-agent/internal/events"
+)
+
+// The `.gps` read of the start's z check (dungeon.StartHands.GPS). `.gps` is a plain GM line (no ".bot " in front) and the core answers it
+// with several system messages; the one with GroundZ and FloorZ ends the read (a TileX line may follow it).
+const (
+	gpsTotalWait = 3 * time.Second        // the whole read
+	gpsQuietWait = 400 * time.Millisecond // the read ends this long after the last line once a line has come
+)
+
+// GPS selects the agent's own character, waits until the server shows it selected, and sends ".gps": the core reports the unit the GM has
+// selected, so a mob or a bot left selected would be read in the commander's place. It returns the system lines that followed, joined by
+// newlines. An error is a selection or a line that could not be sent, or no reply within gpsTotalWait.
+func (g remoteGame) GPS(ctx context.Context) (string, error) {
+	log := g.c.cur().Log()
+	since := log.Last()
+	if err := g.selectThenGM(ctx, g.AgentGUID(), ".gps"); err != nil {
+		return "", err
+	}
+	return readGPSReply(ctx, log, since, gpsTotalWait, gpsQuietWait)
+}
+
+// readGPSReply collects the system lines the log gets after since: it returns at the line that has "FloorZ" (the one that ends the reply),
+// else quiet after the last line once one has come, else at total with an error when there was none.
+func readGPSReply(ctx context.Context, log *events.Log, since uint64, total, quiet time.Duration) (string, error) {
+	tctx, cancel := context.WithTimeout(ctx, total)
+	defer cancel()
+	var lines []string
+	cursor := since
+	for {
+		p := log.Read(events.Query{Since: cursor, Kinds: []string{events.KindSystem}, Limit: events.MaxLimit})
+		for _, e := range p.Events {
+			if e.Text == "" {
+				continue
+			}
+			lines = append(lines, e.Text)
+			if strings.Contains(e.Text, "FloorZ") {
+				return strings.Join(lines, "\n"), nil
+			}
+		}
+		cursor = p.Next
+		if p.More {
+			continue
+		}
+		wctx, cancel := tctx, context.CancelFunc(func() {})
+		if len(lines) > 0 {
+			wctx, cancel = context.WithTimeout(tctx, quiet)
+		}
+		err := log.Wait(wctx, cursor)
+		cancel()
+		if err != nil {
+			if err := ctx.Err(); err != nil {
+				return "", err
+			}
+			if len(lines) == 0 {
+				return "", context.DeadlineExceeded
+			}
+			return strings.Join(lines, "\n"), nil
+		}
+	}
+}

cmd/turtle-agent/commander_gps_test.go

@@ -0,0 +1,109 @@
+package main
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/pjerra/turtle-agent/internal/events"
+	"github.com/pjerra/turtle-agent/internal/opcode"
+	"github.com/pjerra/turtle-agent/internal/packet"
+	"github.com/pjerra/turtle-agent/internal/session"
+)
+
+func gpsSys(l *events.Log, text string) { l.Append(events.Event{Kind: events.KindSystem, Text: text}) }
+
+// The reply is the system lines after the send, up to the one with FloorZ; earlier lines and other kinds are not part of it.
+func TestReadGPSReplyCollectsTheLinesToFloorZ(t *testing.T) {
+	log := events.New(100)
+	gpsSys(log, "old line")
+	since := log.Last()
+	go func() {
+		time.Sleep(20 * time.Millisecond)
+		gpsSys(log, "Map: 70 (Uldaman)")
+		log.Append(events.Event{Kind: events.KindChat, Text: "somebody says hi"})
+		gpsSys(log, "X: 1 Y: 2 Z: 3")
+		gpsSys(log, "GroundZ: 3.000000 FloorZ: 3.000000 Have height data (Map: 1 VMap: 1)")
+	}()
+	got, err := readGPSReply(context.Background(), log, since, 2*time.Second, 400*time.Millisecond)
+	if err != nil || got != "Map: 70 (Uldaman)\nX: 1 Y: 2 Z: 3\nGroundZ: 3.000000 FloorZ: 3.000000 Have height data (Map: 1 VMap: 1)" {
+		t.Fatalf("%q %v", got, err)
+	}
+}
+
+// A reply without a FloorZ line ends on a quiet gap after its last line; no reply at all is an error after the total wait.
+func TestReadGPSReplyQuietAndTimeout(t *testing.T) {
+	log := events.New(100)
+	since := log.Last()
+	gpsSys(log, "There is no such command")
+	start := time.Now()
+	got, err := readGPSReply(context.Background(), log, since, 2*time.Second, 50*time.Millisecond)
+	if err != nil || !strings.Contains(got, "no such command") || time.Since(start) > time.Second {
+		t.Fatalf("%q %v after %s", got, err, time.Since(start))
+	}
+	if _, err := readGPSReply(context.Background(), log, log.Last(), 80*time.Millisecond, 50*time.Millisecond); err == nil {
+		t.Fatal("no reply must be an error")
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if _, err := readGPSReply(ctx, log, log.Last(), time.Second, 50*time.Millisecond); err == nil {
+		t.Fatal("a cancelled context must be an error")
+	}
+}
+
+// `.gps` reports the unit the commander has selected, so the read selects the agent's own character (guid 0x2A) first and sends the line
+// only once the server shows that selection. A stranger left selected (a mob, a bot) must not be read in its place.
+func TestGPSSelectsTheCommanderBeforeTheLine(t *testing.T) {
+	const stranger = packet.GUID(0x4D2)
+	r := newRig(t)
+	r.srv.Send(opcode.SMSGUpdateObject, selfBlock(stranger)) // the server shows a stranger selected
+	g := remoteGame{c: &commanderService{cur: func() *session.Session { return r.s }}}
+	type reply struct {
+		text string
+		err  error
+	}
+	done := make(chan reply, 1)
+	go func() {
+		text, err := g.GPS(context.Background())
+		done <- reply{text, err}
+	}()
+	// The server applies each selection and echoes it. A neutral selection of nothing may come first (when GPS starts before the session
+	// read the create block, the field is unknown: session.SelectConfirmed); anything else, or a line on anything but the commander, fails.
+	var ops []uint16
+	inForce := stranger
+	for len(ops) == 0 || ops[len(ops)-1] != opcode.CMSGMessagechat {
+		p, err := r.srv.Next(2 * time.Second)
+		if err != nil {
+			t.Fatalf("after %v: %v", ops, err)
+		}
+		switch p.Op {
+		case opcode.CMSGSetSelection:
+			guid := packet.NewReader(p.Body).GUID()
+			if guid != 0x2A && (guid != 0 || len(ops) != 0) {
+				t.Fatalf("selected %#x, not the commander (0x2A) or a first neutral selection of nothing", uint64(guid))
+			}
+			inForce = guid
+			ops = append(ops, p.Op)
+			r.srv.Send(opcode.SMSGUpdateObject, selfValues(guid)) // the server's echo of the selection
+		case opcode.CMSGMessagechat:
+			if inForce != 0x2A {
+				t.Fatalf("the .gps line was sent with %#x selected, not the commander", uint64(inForce))
+			}
+			if !strings.Contains(string(p.Body), ".gps") {
+				t.Fatalf("chat line %q", p.Body)
+			}
+			ops = append(ops, p.Op)
+			r.s.Log().Append(events.Event{Kind: events.KindSystem, Text: "X: 1.000000 Y: 2.000000 Z: 3.000000 Orientation: 0.000000\n" +
+				"GroundZ: 3.000000 FloorZ: 3.000000 Have height data (Map: 1 VMap: 1)"})
+		}
+	}
+	select {
+	case got := <-done:
+		if got.err != nil || !strings.Contains(got.text, "FloorZ: 3.000000") {
+			t.Fatalf("%q %v", got.text, got.err)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("GPS did not return")
+	}
+}

cmd/turtle-agent/commander_methods.go

@@ -238,6 +238,9 @@ func (g remoteGame) ViewStats() tbm.ViewStats                 { return g.c.feed.
 // Team is the agent's own side (dungeon.TeamSource): the feed carries no race, and the owned bots share the account's faction.
 func (g remoteGame) Team() string { return g.c.cur().Team() }
 
+// BotTeam implements dungeon.BotTeamer: a unit's side from its race in the agent's object store ("" when the unit is not in view).
+func (g remoteGame) BotTeam(guid packet.GUID) string { return session.Team(g.c.cur().RaceOf(guid)) }
+
 // BotLines implements dungeon.BotLiner: a plain `.bot maintenance|inv|logout <bot>` and the lines it was answered with.
 func (g remoteGame) BotLines(ctx context.Context, command string, wait time.Duration, done func(line string) bool) ([]string, bool, error) {
 	return g.c.cmdr.Lines(ctx, command, wait, done)
@@ -376,33 +379,15 @@ func (g remoteGame) GMVisible(ctx context.Context, on bool) error {
 // gmSelectConfirmWait is how long the server is given to show a selection before a line that acts on it is given up on.
 var gmSelectConfirmWait = 3 * time.Second
 
-// selectConfirmed selects the unit and waits until the SERVER shows it as the agent's selection (the target field of the agent's own object,
-// which the core sends back after it handled CMSG_SET_SELECTION). The core queues that packet (map thread) apart from a GM's chat line (world
-// thread), so a line sent right after can run on the selection from before: none (the sender itself) or a stale one, which can be another
-// player. Run 6b: `.instance groupunbind all` answered "Glacienne is not in a group" for a selected Lcwarra. An error, with nothing sent, when
-// the server does not show the selection in time.
+// selectConfirmed selects the unit (0: none) and waits until the SERVER is known to have it in force as the agent's selection
+// (session.SelectConfirmed: an echo of the target field of the agent's own object that answers this select and not an older one, nor a
+// combat or stun rewrite of the field). The core queues that packet (map thread) apart from a GM's chat line (world thread), so a line sent
+// right after can run on the selection from before: none (the sender itself) or a stale one, which can be another player. Run 6b:
+// `.instance groupunbind all` answered "Glacienne is not in a group" for a selected Lcwarra; issue #296: a stale echo of the lead, with a
+// stranger's select pending behind it, let `.additem` run on the stranger. An error, with nothing sent, when the server does not show the
+// selection in time.
 func (g remoteGame) selectConfirmed(ctx context.Context, guid packet.GUID) error {
-	s := g.c.cur()
-	if _, err := s.Target(ctx, guid, ""); err != nil {
-		return err
-	}
-	timer := time.NewTimer(gmSelectConfirmWait)
-	defer timer.Stop()
-	tick := time.NewTicker(25 * time.Millisecond)
-	defer tick.Stop()
-	for {
-		sel, ok := s.ServerSelection()
-		if ok && sel == guid {
-			return nil
-		}
-		select {
-		case <-ctx.Done():
-			return ctx.Err()
-		case <-timer.C:
-			return fmt.Errorf("the server did not show %v as the agent's selection within %s (it shows %v): not sending a line that acts on the selection", guid, gmSelectConfirmWait, sel)
-		case <-tick.C:
-		}
-	}
+	return g.c.cur().SelectConfirmed(ctx, guid, gmSelectConfirmWait)
 }
 
 // gmSelectAttempts is how many times selectThenGM selects and confirms again when the selection changed after the confirmation.
@@ -567,28 +552,17 @@ func (g remoteGame) GoXYZ(ctx context.Context, mapID uint32, at dungeon.Point) e
 // around the commander. The selection is cleared first and the server is waited for to show it cleared, else the line would act on that
 // one unit alone (or fail on a player).
 func (g remoteGame) Respawn(ctx context.Context) error {
-	s := g.c.cur()
-	if err := s.ClearTarget(ctx); err != nil {
-		return err
-	}
-	timer := time.NewTimer(gmSelectConfirmWait)
-	defer timer.Stop()
-	tick := time.NewTicker(25 * time.Millisecond)
-	defer tick.Stop()
-	for {
-		if sel, ok := s.ServerSelection(); ok && sel == 0 {
-			break
-		}
-		select {
-		case <-ctx.Done():
-			return ctx.Err()
-		case <-timer.C:
-			sel, _ := s.ServerSelection()
-			return fmt.Errorf("the server did not show the selection cleared within %s (it shows %v): not sending .respawn", gmSelectConfirmWait, sel)
-		case <-tick.C:
-		}
+	return respawnUnselected(ctx, g.c.cur())
+}
+
+// respawnUnselected clears the selection, waits until the server is known to have it cleared (a stale echo of an earlier clear, or the
+// field cleared by the end of a fight, does not count), and sends ".respawn" only while that stands (selectThenGM with no unit).
+func respawnUnselected(ctx context.Context, s *session.Session) error {
+	g := remoteGame{c: &commanderService{cur: func() *session.Session { return s }}}
+	if err := g.selectThenGM(ctx, 0, ".respawn"); err != nil {
+		return fmt.Errorf("respawn with nothing selected: %w", err)
 	}
-	return s.GM(ctx, ".respawn")
+	return nil
 }
 
 // WalkSelf is walk_path for the agent's character.

cmd/turtle-agent/dungeon_leader_pulltest.go

@@ -2,8 +2,6 @@ package main
 
 import (
 	"context"
-	"fmt"
-	"time"
 
 	"github.com/pjerra/turtle-agent/internal/brain"
 	"github.com/pjerra/turtle-agent/internal/dungeon"
@@ -16,28 +14,7 @@ import (
 // Respawn sends the character's own ".respawn" with nothing selected (dungeon.Respawner), as the commander's does: the selection is cleared
 // first and the server is waited for to show it cleared, else the line would act on that one unit alone.
 func (g *sessionGame) Respawn(ctx context.Context) error {
-	s := g.cur()
-	if err := s.ClearTarget(ctx); err != nil {
-		return err
-	}
-	timer := time.NewTimer(gmSelectConfirmWait)
-	defer timer.Stop()
-	tick := time.NewTicker(25 * time.Millisecond)
-	defer tick.Stop()
-	for {
-		if sel, ok := s.ServerSelection(); ok && sel == 0 {
-			break
-		}
-		select {
-		case <-ctx.Done():
-			return ctx.Err()
-		case <-timer.C:
-			sel, _ := s.ServerSelection()
-			return fmt.Errorf("the server did not show the selection cleared within %s (it shows %v): not sending .respawn", gmSelectConfirmWait, sel)
-		case <-tick.C:
-		}
-	}
-	return s.GM(ctx, ".respawn")
+	return respawnUnselected(ctx, g.cur())
 }
 
 // CombatMark is the position of the event log now (dungeon.CombatMeter).

cmd/turtle-agent/dungeon_methods.go

@@ -124,6 +124,10 @@ type dungeonRunParams struct {
 	// (AUTO-IMPROVE step 0), so its waypoints and pull order are unchecked. Without it such a plan is refused.
 	AllowDraft bool      `json:"allow_draft,omitempty"`
 	FromLeg    *legParam `json:"from_leg,omitempty"`
+	// FromStep is an observed run's exact start step in the run leader's own plan: the step number `.bot run status` shows, from 1
+	// (README "Observe mode"). It is the fallback for a from_leg / from_pull_group whose step cannot be mapped offline (the deployed rows
+	// were exported with other options); observe only, and it excludes from_leg and from_pull_group.
+	FromStep *int `json:"from_step,omitempty"`
 	// FromPullGroup starts the run inside from_leg, at that pull group (remote mode; README "Start anywhere"): the commander's own GM move
 	// brings the party to the group's gather spot. StartHere keeps the old from_leg (no move: the run starts where the lead bot stands).
 	// Pulltest runs one pull group as a scored scenario instead of the plan (README "Pull test").
@@ -278,6 +282,16 @@ type observeParam struct {
 	MaxRunS     float64 `json:"max_run_s,omitempty"`
 	StallS      float64 `json:"stall_s,omitempty"`
 	PausedWaitS float64 `json:"paused_wait_s,omitempty"`
+	// Maintenance sends `.bot maintenance <bot>` to every bot at the preflight (and at the hire check); off by default. Maintenance
+	// walks a bot to a vendor for repairs and supplies: right after the autogear of a hire that scatters the party across the maps, and
+	// the run leader pauses with "the lead bot is not on the plan's map". The kit check's inventory and talent reads run either way.
+	Maintenance bool `json:"maintenance,omitempty"`
+	// AllowFarStart lets a partway start (from_leg, from_pull_group, from_step) go on although the lead bot stands more than 80 yd
+	// from the start step's point; the note says so. Off by default: a party in the wrong place is refused before `run start`.
+	AllowFarStart bool `json:"allow_far_start,omitempty"`
+	// KeepLootSetting leaves the bots' corpse looting as the operator set it: the start sends no `.bot behavior <bot> loot on` (the undo
+	// of a boss `loot off` a crashed run left in place). Off by default. Observe only; a driven run always sends the undo.
+	KeepLootSetting bool `json:"keep_loot_setting,omitempty"`
 }
 
 type dungeonRunResult struct {