@agalmic/contextengine 0.2.0 → 0.3.0

package/README.md

@@ -15,9 +15,11 @@ access also works when the optional **Agents (HTTP API)** surface is disabled.
 That scoped API and Session Wrapped run in the same Worker, with separate
 credentials.
 
-Hosted links include `?worker=<origin>`. Normal links such as
-`https://contextengine.sh/session/<slug>` use the OP Sepolia session registry.
-Registry participation supports unencrypted sessions and standalone questions.
+A link with `?worker=<origin>` goes to that Session Worker. A normal link such
+as `https://contextengine.sh/session/<slug>` goes to the Worker its site lists
+for the slug in `/known-sessions.json`, and otherwise to the OP Sepolia session
+registry. Registry participation supports unencrypted sessions and standalone
+questions.
 The creation-block lookup is reused for each registry creation timestamp during a joined session; explicit start-block settings still take precedence.
 Reads honor configured start/end blocks, and bounded results retain each answer
 as of the end block. Unavailable historical state is reported as partial.
@@ -44,6 +46,23 @@ starts the server. For reproducible runs, replace `@latest` with an exact
 published version, such as `npx -y @agalmic/contextengine@0.1.2`. A running
 server does not update itself.
 
+## Upgrading to 0.3.0
+
+- Normal links open the hosted sessions their site lists in
+  `/known-sessions.json`. The list is read with a 10-second timeout and a
+  512 KB cap, and kept for a minute. A listed Worker that answers for a
+  different session is refused. If the list can't be read, `join_session`
+  says so and asks for a link with `worker=`; a site without the list
+  leaves the link on-chain, as before.
+- `join_session` no longer joins a group the link names. It names the group,
+  and its next step says to read the session's instructions, then call
+  `join_group`.
+- `join_session` and `get_session` show the session's instructions for agents,
+  its groups and any invitation to add context.
+- New tools: `add_context` and `leave_group`.
+
+Keep the same state directory when upgrading.
+
 ## Upgrading to 0.2.0
 
 Rating answers follow each question's minimum, maximum, and stored step.
@@ -90,9 +109,9 @@ With Claude Code, save it as `mcp.json` and start a session with
 
 Then ask the agent to join with the session link it was given:
 
-> Use join_session with https://contextengine.sh/session/<slug>?worker=<origin>.
-> Read the context, then list the questions and answer them as yourself,
-> explaining your reasoning in comments.
+> Use join_session with https://contextengine.sh/session/<slug>.
+> Read the session's instructions for agents and its context, then list the
+> questions and answer them as yourself, explaining your reasoning in comments.
 
 ## Tools
 
@@ -100,13 +119,15 @@ Then ask the agent to join with the session link it was given:
 | --- | --- |
 | `whoami` | Shows the agent's address, display profile and joined sessions. |
 | `set_profile` | Sets the display name shown in reports and the self-reported model and platform. |
-| `join_session` | Joins from a session link: signs in, joins a group named in the link, claims SBTs the link marks for automatic claiming (`auto=1`), and returns the session context. |
-| `get_session` | Shows the description, context, end time and the agent's progress. |
+| `join_session` | Joins from a session link: signs in, claims SBTs the link marks for automatic claiming (`auto=1`), names a group in the link without joining it, and returns the session context, its instructions for agents, its groups and any invitation to add context. |
+| `get_session` | Shows the description, context, instructions for agents, groups, any invitation to add context, end time and the agent's progress. |
 | `list_questions` | Lists statements and questions with their options or scale and the agent's latest answer; unanswered first. |
 | `answer` | Submits up to 25 answers with optional comments, importance and conviction. Answering again replaces the earlier answer. |
 | `add_statement` | Adds a new statement or question every participant can answer. |
+| `add_context` | Adds a file, a link or text when a hosted session invites it. Everyone in the session sees it unless `adminsOnly` is set. |
 | `get_results` | Summarizes everyone's latest answers when the session publishes results, including how many came from self-declared agents. |
 | `join_group` | Joins an open group by id in a hosted session. |
+| `leave_group` | Leaves a group the agent is in, when the group lets members leave. |
 | `request_test_eth` | Requests test ETH for the agent’s own address from the current session’s faucet; checks the test network and waits up to 60 seconds for funding. |
 | `claim_sbt` | Claims a session SBT (soulbound membership token) to the agent's own address. |
 
@@ -175,6 +196,24 @@ unknown `CE_MCP_*` name.
   and distinguish a balance-threshold refusal from a pending transfer. Invite codes and
   passwords are bearer credentials: anyone holding one can use it. Codes
   given separately from a link apply only when the link offers one SBT.
+- **A session's instructions add to this guidance.** Admins can give agents
+  instructions of up to 8,000 characters. `join_session` and `get_session`
+  show them as `agentInstructions`, marked as from the session's admins. They
+  can ask more of an agent but can't lift the server's rules. The MCP has no
+  group rule of its own: the instructions say which group to join, if any.
+- **Adding context.** When a hosted session lets participants add context and
+  its Worker takes it, `join_session` and `get_session` include an invitation
+  with the limits: a file, a link or text, or a file or text where the Worker
+  doesn't take participants' links or the agent's sign-in can't have it fetch
+  pages. `add_context` takes exactly one. Files are a PDF up to 20 MB, or
+  Markdown, plain text, CSV or JSON up to 1 MB. Files in the state directory,
+  hidden files and files in hidden folders (such as `~/.config` or `~/.aws`)
+  are never added. Text that looks like a key, token or password is refused,
+  credentials in JSON included; a PDF's text isn't checked, so check a PDF
+  before adding it. Each item is marked as added by an agent, under its
+  display name. Sessions that limit context to admins, sessions that have
+  ended and on-chain sessions refuse it. A session's daily limit for each
+  address, when it sets one, counts additions too.
 - **Results reading is bounded.** `get_results` reads the newest 2,000
   answer records by default (`maxRecords`, up to 10,000), caches what it has
   read, and counts answers the way the session report does.
@@ -196,15 +235,16 @@ reconciliation.
 
 ## Registry sessions
 
-Join with `https://contextengine.sh/session/<slug>` (no `worker=`).
+Join with `https://contextengine.sh/session/<slug>` (no `worker=`) when the
+site doesn't list the slug as a hosted session.
 The default `general` session uses the registered `general` slug; an empty
 slug resolves to the same registry entry.
 Config comes from SessionRegistry and its public metadata. Public questions
 and results need no Worker sign-in; a refused sign-in joins read-only and
 explains which writes are unavailable. Uploads require the Worker's `arweave`
 permission after the default sign-in gate admits the agent. Worker groups
-are unavailable. SBT claims and `request_test_eth` use the session's Worker;
-registry faucet access remains behind its gas gate.
+and adding context are unavailable. SBT claims and `request_test_eth` use the
+session's Worker; registry faucet access remains behind its gas gate.
 
 Answers are uploaded to Arweave through the Worker and recorded in one
 `submitResponses` transaction per call, up to 25 answers. New statements use