Team server

A team server lets the people of one team learn from each other's sessions. Without it, each person's Besydr keeps its lessons and generated rules on that person's machine, so a teammate's agent rediscovers what yours already learned. A team server is the same besydr program started with besydr instance on a machine of your own. It holds the team's shared lessons, makes a team rule when two people state the same rule, tries generated rules across everyone's sessions, and manages people and keys. It needs a Team licence. Nothing here has been measured on a real team yet.

What it shares, and what stays on each machine

Each person's Besydr still does all its work on that person's machine: it reads the transcript, checks the agent's work and writes lessons there. For a session in a team repository it also sends some of those lessons to the team server and reads the team's lessons back.

What a session learned Where it goes
A fact about the project or a work memo (lesson kinds orientation and experience) To the team server at once, for everyone who works in that repository. It is kept on the machine only in the copy of the team's lessons.
A rule you stated about the project Kept on your machine and sent to the team server as yours alone. Nobody else sees it until a second person states the same rule; then the server makes one team rule from the two (see Rules two people state).
A global lesson, one that holds in every project Stays on your machine. It is never sent.

What is sent is the lesson record: its title, text, kind, the quote of a rule you stated, and where in the session it came from (a session id and message number, which point into your machine's records). Code, transcripts and tool output are never sent. Besides lessons, a session reports which team lessons and rules it was given, which tool calls a team rule stopped, and each turn's check result for the team's rules, as ids and counts. A session is named in these reports by a hash of its id.

The team server runs on your machines. It sends nothing to besydr.com except its own licence activation.

Set up the server

  1. Install Besydr on the server machine as described in Install. The server needs no coding agent.
  2. Give the server a data directory of its own. A data directory holds one person's work or one team server's store, never both: in a shared one your own rules would go out to the team and the team's rules would act in your sessions as your own. Besydr enforces this. besydr instance refuses a data directory that already holds a person's sessions or lessons, and a person's Besydr refuses a data directory that holds a team server's database. Run the server as its own system user, or set BESYDR_DATA_DIR for every command below, for example BESYDR_DATA_DIR=/var/lib/besydr-team. The config file then lives in that directory too, unless BESYDR_CONFIG_PATH names another.
  3. Install the Team licence on the server and activate it: besydr licence install besydr.licence (see Licence). The server counts as one of the licence's machines.
  4. Set the address and, for a server other people reach over the network, the HTTPS certificate in the [instance] table of the server's config file (see Configuration). The server refuses to listen on an address other than a loopback one without a certificate, because keys and lessons would cross the network in clear text. To serve HTTPS from a proxy instead, keep the default listen = "127.0.0.1:7870" and point the proxy at it.
  5. Set the server's models in its config file as on a person's machine (see Configuration). The server uses the model to generate rules from the team's lessons, and the decision model to judge whether two people's rules say the same thing. Without a decision model, people's rules stay their own.
  6. Start it: besydr instance. The first start prints the admin key once; keep it, because the server holds only its hash. besydr instance admin-key replaces it, and the old key stops working. Run besydr instance under your service manager so it starts with the machine.

The server refuses to start without a valid Team licence that is activated on this machine and includes this build, and it says which of these is missing. A person's own Besydr keeps working without any of this.

Add people

The admin adds people with the admin key, either on the server's web page (see The admin page) or from any machine with the besydr team commands, the key in BESYDR_ADMIN_KEY and the server's address in --url:

export BESYDR_ADMIN_KEY=bsa_...
besydr team --url https://besydr.example.com add "Ana Lima"

Adding a person issues their key, shown only then. Give it to the person. people lists everyone with their keys, key <person> issues another key, revoke <key id> stops one key, and remove <person> removes the person and revokes all their keys. A person is named by the id that people shows, or by name when the name is unique.

The server holds at most as many people as the licence has seats. Adding one more is refused with the number of seats and where to buy more. To grow, buy added seats for the same licence on the pricing page; you receive the licence file again with the higher seat count and the same end of updates. Install it on the server with besydr licence install; the server reads the seats again each time a person is added, so no restart is needed. Members keep the file they have.

Connect a person's machine

Each member installs the team's licence file on their own machines with besydr licence install, as for a personal licence. Then they add the team to their config file:

[[teams]]
name = "acme"
url = "https://besydr.example.com"
key = "bsk_..."
remotes = ["[email protected]:acme/api.git", "[email protected]:acme/web.git"]
folders = ["~/work/acme"]
Setting Meaning
name The name commands and messages use for the team. Each entry needs a different one.
url The team server's address. It must be https://, except on a loopback address such as http://127.0.0.1:7870.
key The person's key from the admin.
remotes Git remotes of the team's repositories, in any form Git accepts (git@host:owner/repo.git, https://host/owner/repo).
folders Folders whose repositories belong to the team. ~ stands for your home folder.

An entry needs at least one remote or one folder. A person can list several teams; each session shares with one of them.

Which team a session uses

When a session starts, Besydr reads the Git remote of the session's repository, origin first. A team that lists that remote is chosen. Otherwise a team that lists a folder holding the session's folder is chosen. A session in a repository without a remote shares with no team, even in a listed folder, because the server files everything under the remote. A session that matches no team works as it does without one.

The server files a project under its remote in a fixed form: the host and path in lower case, without the user, port, scheme or .git. [email protected]:Acme/api.git and https://github.com/acme/api are the same project, github.com/acme/api.

How a session reads the team's lessons

At the start of a session Besydr asks the team server, in the background, for the team's lessons and rules for the repository, and writes them into a copy under the data directory (learning/.teams/). The session does not wait for it. The team's lessons join the recall from the next request after the copy is written, after your own lessons at each step: team-wide lessons after your global ones, and the team's lessons of the project after yours. The team's rules apply from the next session start.

Besydr asks again before recalling lessons, at most once a minute for each repository and role, so the copy stays fresh during a long session and comes back after the Besydr server restarts. A session reads the team's lessons only while the last request for its repository and role in the running Besydr server succeeded. When the team server cannot be reached, sessions use your own lessons alone, and the lessons they make are stored on your machine as if there were no team; Besydr then asks again a minute later. The team's rules from the last request that worked stay in force meanwhile, including one the admin retired since.

Rules two people state

A rule you state stays yours: it is stored on your machine and sent to the team server as yours alone. When someone else states a rule, the server compares it with the most alike rules other people stated, and asks the decision model whether the two say the same thing. If they do, the server makes one team rule that cites both quotes: a team project rule when both came from one repository, or a team rule for every repository when they came from two. The two people's own rules stay, marked as replaced; if the team rule is deleted, they are each person's own again. Without a decision model, or when it does not answer, nothing is widened, and the rule is compared again when the next person states a similar one.

When you correct a rule you stated, the corrected rule replaces the old one on the team server too. A rule you delete on your machine with besydr learning or besydr ui stays on the team server until you delete it there with besydr team delete.

The server trusts every person's key: the lessons, check results and reports sent with a key count as that person's. Give a key only to a member of the team, and revoke it when they leave.

Generated rules on a team

The team server generates rules from the team's lessons of a project, as a person's Besydr does from that person's own (see Learning), at most once a day per project after it got a new lesson. Every session in that repository receives the project's generated rules, with their trial, and reports each turn's check result. The server counts the results of all sessions together, so a team rule reaches the number of results it needs for a decision sooner than one person's would. A rule with a known effect is promoted, and one without is retired, by the same test as on one machine.

A guard from the team stands even when your words in the session ask for the call it stops; only your own guards can be lifted that way. Stop a team guard with besydr team retire.

[learning.evolution] enabled = false in the server's config file is the team's kill switch: the server then sends no generated rules to any session and ignores their results. A team rule on a person's machine cannot be approved, rejected or rolled back there; besydr learning evolution says so and points to besydr team retire.

The admin page

Open the server's address in a browser and paste a key. A person's key shows that person's sessions and figures. The admin key shows everyone's, and a Person filter narrows the overview, the sessions and the missed lessons to one person. A click on a column heading sorts a table by that column; a second click reverses the order. A small i beside a label explains the term, and the How it works page lists every term the pages use.

  • Overview: the completion checks of each day by verdict, the tool calls a team guard stopped, and the team lessons given, missed and stored. Point at a day for its figures; click it for its sessions. What Besydr's own model calls cost, the work a check sent back and the tokens it saved stay on each person's machine, in besydr ui.
  • Sessions: each session with its person and project, its checks, the lessons and rules it was given and the tool calls a guard stopped. Opening one shows its timeline: each check's verdict, the lessons and rules given, the stopped calls and the missed lessons. What a check found and which tool a call used stay on the person's machine.
  • Lessons: the team's lessons, with search, the person who wrote each, flags, and the sessions that were given each one. Anyone can flag a lesson as wrong, so that its author and the admin see it; the list shows how many flags each lesson has. Its author or the admin can delete it. A rule one person stated is shown only to that person and the admin. Missed lists the lessons the recall did not give a session, found because the person stated the same lesson again in it.
  • Rules: every generated rule with its state, trial results and the history of its state. The admin, or a person who wrote one of the lessons a rule came from, can retire it.
  • People (admin only): the people, their keys, and the seats used out of the licence's seats. Add a person, issue or revoke a key, or remove a person.

The key stays in the browser tab until it is closed. The page loads nothing from other sites.

Commands

The besydr team commands work on a person's machine with the key from its [[teams]] entry. With one team listed they use it; with several, name one with --team. --json prints the answer as JSON. See Command line.

Command What it does
besydr team lessons [--project <remote>] List the team's lessons you can see, for one repository or all.
besydr team flag <id> Mark a lesson as wrong.
besydr team delete <id> Delete a lesson you wrote; the admin can delete any.
besydr team rules List the team's generated rules.
besydr team retire <id> Stop a generated rule.
besydr team people, add, remove, key, revoke Manage people and keys; these need the admin key.