pinecall 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ab6b509c4c3b476fdf67322bdef9e0c37d86893204ca487b5bb369aa0f7490eb
+  data.tar.gz: 05b84996a5e4b1deb8f73e254d539b51f0768f84dde7654ed35bb9b7dac95967
+SHA512:
+  metadata.gz: '07945d49d0bcc224e39f5f6976e34ed9ff9cbf6cec56b0b1d8151ac7d0f538561fadaff755a8d0d52cf9d9b8ac5e0c323dcaff8267a28092776ff9677db5c61e'
+  data.tar.gz: 04d24ebd3800a149e3958fb34719b7daae2be9d6405c236cb3a297ba44e120ea7f168ba181a7291a9a4cdc002739d83889b3a97aa24476e4350d8a4529888ef2

data/CHANGELOG.md

@@ -0,0 +1,167 @@
+# Changelog
+
+Every change a person using this gem would notice. The format is
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); nothing is versioned yet, because a
+version number is the human's call.
+
+## [Unreleased]
+
+## [0.0.1] — The first release: an agent as a Ruby class (2026-10-09)
+
+### Fixed
+- **The tutorial prints the prompt the gem sends**: the framework's rules and the channel's words
+  are in English, and the `<channel>` block was missing. Its `Pinecall::Client` example no longer
+  needs `PINECALL_URL`, which `pinecall link` writes only for a gateway other than Pinecall's.
+- **`pinecall start` drains a Ruby agent whole on Ctrl-C or a SIGTERM.** The CLI passes the signal on
+  and closes the child's stdin together, and the serve entry took the second as "leave now": it
+  closed the socket mid-drain, with tools still running. Only a second signal cuts a drain short,
+  as in TypeScript; the drain line is printed. The serve entry no longer prints its own
+  `answering on` line, which the CLI already says.
+- **Leaving after the socket closed is quiet.** When the gateway's socket closed just before the
+  drain was asked, `pinecall test` and `chat` ended with `Pinecall::NotConnected: agent.drain: the
+  gateway is not connected`; a drain with no socket has nothing to hand over, and says so.
+- **A judged call's score reaches the agent.** The runtime's `call.score` says which judge model
+  gave it (`judged_by`), and the gem refused the field: `pinecall simulate --judge` and every
+  judged call printed `CallScore has no field called judged_by` and dropped the score.
+- **`pinecall start`, `chat` and `test` see a Ruby agent register.** The serve entry's lines went
+  to a pipe's buffered `$stdout` and reached the CLI only when the process left, so every verb
+  that waits for `agent.registered` gave up after 30 seconds. Each line is flushed now.
+- **A voice call whose vendor fails over no longer stops the agent.** The runtime writes
+  `vendor.switched` when a stage's fallback switches vendor, and the gem did not know the type: the
+  socket raised `unknown event type` mid-call. `vendor.switched` and `spend.unusual` are in the
+  wire now, both left to `call.on` and `client.on_any`.
+
+### Changed
+- **Breaking: the language is the world's, and the prompt says how to write for the channel** — as
+  the TypeScript package's 0.9.19. `language :es` is refused at load (`pinecall agent set
+  --language es`); the rules and protocols are English for every agent and tell the model to answer
+  in the caller's language; the `identity` block gains `<channel>`: speech, a website's Markdown, or
+  WhatsApp's formatting, by the call's channel and `medium`. `channel_rules false` leaves it out.
+  `call.started.medium` is in the wire (the runtime sends it from this release on, and a gem without
+  it refuses every call), on `CallWorld#medium` and `Client::Call#medium`; serve's `prompt` takes
+  `--medium`. `language` is no longer in `agent.configure`.
+- **Breaking: no CLI, no console, no executable.** The verbs are the one `pinecall` CLI's (npm),
+  the same for a Ruby project as for a TypeScript one, in the same layout
+  (`agents/<slug>/agent.rb`): for `prompt`, `chat`, `test` and `start` it runs `Pinecall::Serve`.
+  `exe/pinecall`, `bin/pinecall`, the vendored console and `pinecall ui`, `run`, `whoami`,
+  `knowledge`, `memory`, `remember` and `keys` are gone, and so are `Client#knowledge`,
+  `#memory_of`, `#memory` and `#provider_keys`: those doors are the CLI's verbs.
+- **Breaking: `Pinecall::Client.new` reads nothing from the environment.** It takes `url:`,
+  `api_key:` and `env:` (`"production"` names production for a person's key); the serve entry
+  reads `PINECALL_KEY`, and no other key variable is read anywhere.
+- **Breaking: a call opens in the state its `call.started` carries.** `Pinecall.mount` takes no
+  `opening:`: the state a golden, a persona or a chat's `?state=` asked for rides the call, and the
+  bridge applies it after `on_call` and before the first render. `Testing::Gateway#call_started`
+  takes `state:`.
+- **No `pinecall-protocol` dependency.** The gem keeps the runtime's wire it speaks in
+  `lib/pinecall/wire/` (`Pinecall::Wire`: the shapes, the validator, the codec, the reducer), held
+  to the runtime's golden call log; `Pinecall::Protocol` is `Pinecall::Wire` and `ProtocolError` is
+  `WireError`.
+- **Breaking: the class is code, the world is environment.** A class declares the contract — its
+  `language`, `state` and `stage`, its `tool`s, `accepts`, its view — and nothing it runs on.
+  `voice`, `llm`, `stt`, `greeting`, `hangup`, `says`, `hears`, `memory`, `record`, `knowledge`
+  and `docs` in a class body now raise `DeclarationRefused` when the class loads, before a prompt
+  is printed or a gateway is knocked at, naming the verb that sets each instead:
+  `` `voice` is the world's now, not the class's: pinecall agent set --voice <name> — remove it
+  from the class``. What to run instead, per world, with the Node CLI or the console's Settings:
+  `pinecall agent set --voice | --llm | --stt | --greeting '…' (or --reply '…') | --hangup '…' |
+  --record on|off`, `pinecall lexicon add <word> --say '…'` and `pinecall lexicon hear <word>`,
+  `pinecall memory policy --remember '…' --forget '…'`, `pinecall agent knowledge edit` for what
+  the agent knows by heart, and `pinecall docs attach <base>` for the base it searches. None of
+  them travels on `agent.configure` any more, and the `knowledge` block is the gateway's to fill:
+  the class sends nothing for it, so `pinecall prompt` prints it empty.
+- **A class declares no doors.** `phone`, `whatsapp` and `web` still load and are read by nobody:
+  `agent.register` carries no routes from the class, and nothing counts them. A
+  number is pointed at an agent with `pinecall numbers import <+34…> --agent <slug>`, and every
+  agent can be talked to from a page.
+
+### Added
+- **The console's panel: `panel "Cliente" do |who| … end`**, as the TypeScript package's `@view`.
+  The block draws with the console's catalogue — `panel`, `rows`, `row`, `stat`, `table`, `badge`,
+  `text` — and the nodes are the same JSON, drawn by the console's own parts. The gateway is told the
+  panel's name; serve's `start` answers `view.render` with it, and refuses every other console verb
+  as the TypeScript entry does. A class without one is the 404 the console falls back from.
+- **`agent.on_dev { |verb, data| … }`** answers a console's ask (raise `DevRefused` to refuse with a
+  status); without one an ask is a 501 saying this process answers none. It replaces the fixed "a
+  Ruby agent draws no panel".
+- **`client.on_connected`**, each time the socket is up and every agent on it registered.
+- **`call.opt_out(note)`**: the caller's number joins the org's do-not-call list (`call.opt_out`).
+- **`Pinecall::Serve`, the entry the one `pinecall` CLI starts a Ruby agent with**:
+  `start --file --slug [--console] [--events] [--prod]` holds the agents (its door from
+  `PINECALL_URL`, `PINECALL_KEY`, `PINECALL_ENV` alone; the wire entry by entry on stdout with
+  `--events`; leaves draining on a signal or the end of its stdin) and `prompt --file --slug
+  [--state field=json]… [--show-machine]` prints a prompt. `Pinecall.serve(klass, url:, api_key:,
+  env:)` holds one inside your own Ruby process. The client gains `drain`, `on_entries`,
+  `on_stopped` and the `pinecall-env` header, registers its machine as `host`, and answers a
+  console's ask with `a Ruby agent draws no panel`. `docs/production.md` says how a server runs it.
+- **A call handed over mid-conversation is served.** On `call.attached` (another process drained
+  or died) the agent opens in the state the gateway kept, with no `on_call`; one this process
+  already serves sends its whole prompt again. A call knows the code it claimed (`call.claimed`)
+  and the eval run that opened it. `Testing::Gateway#call_attached(state:)`.
+- **`examples/clinica_norte` is the TypeScript example's agent, in Ruby**, in the one CLI's layout
+  (`agents/clinica-norte/`, `docs/clinica-norte/`, `test/clinica-norte/`): the same agenda —
+  specialties, slots booked by id, a day resolved to a date — the same documents, the same three
+  extraction cases and the same eleven goldens. `rake ring1` runs them through the CLI.
+- A stage restored from JSON — a golden's, `call.started.state` — is the declared stage it names.
+- **The whole call.** `call.transfer(to, mode:)` and `call.attention(reason, wait_s:)` block until
+  the log answers (a `Transferred`, an `Attended`); `call.hold`, `unhold`, `dtmf(digits)`,
+  `claim(code)` (then `call.claimed`) and `callback(number, at:, note:)` are one command each.
+  `knowledge.search(query, k:)` — or `call.search` — searches the bases attached to the agent
+  through the gateway, and a class that searches registers `uses_knowledge`. The view is rendered
+  again on the caller's turn, on a claim and on recall, and reads `call[:claimed]`. The call ending
+  answers every verb still waiting. `Testing::Gateway#finds` and `#searched` for ring 0.
+- The wire reads `call.started`'s `worker`, which the runtime writes on every spoken call: until
+  now a Ruby app refused a phone call's first entry.
+- The wire reads `call.started`'s `state`, the state a call opens in when its opener asked for
+  one, and `agent.register` may carry `answers_dev`. Nothing sends or reads either yet.
+- **`pinecall remember [PATHS]`**, and `client.memory.extraction(slug, cases)` — the goldens
+  the memory policy is held to, which is the write side and the half that persists. A case is one
+  call already held (both speakers, in `said`), the facts memory already holds (`holds`), and what
+  must come of the hang-up's one model call: which categories got a fact (`writes`), which never
+  did (`never`), which values must not survive in any fact's text (`never_says`), and which held
+  facts the call contradicted (`invalidates`) — its mirror included, so a model that supersedes
+  whatever it touches is caught too. A case may `plants` sentences somebody tried to get into
+  memory, and planting one IS the assertion that admission refuses it. Nothing asks a model whether
+  two sentences mean the same thing: a category is your own word, a value is a literal, a
+  supersession is an id. The class is mounted in this terminal, because the tool names admission
+  refuses a fact for are the class's own declaration; the one
+  model call per case runs in the gateway on the org's keys. Exits 1 when a case did not hold.
+  `test/memory` beside the `agent.rb` by default; Clínica Norte ships three.
+- `pinecall memory eval [GOLDEN] [--k N]`, and `client.memory.eval`: the other table's golden.
+  A list of `{ "holds", "asks", "expects" }` — what memory holds about a question's contact, what
+  the caller said, and the fact or facts that should come back — asked of `recall`, and `recall@k`
+  and `nDCG@10` printed, computed by code with no model. No contact of the org is read or written:
+  each question's facts go to a scratch contact and are deleted again, which is what makes the
+  figures the real ranking. A fact answers when what came back CONTAINS what was expected, folded
+  for case, accents and whitespace, because a fact is a sentence a model wrote. Names every
+  question memory did not answer whole with what came back instead and exits 1 when anything did.
+  Clínica Norte ships one of seven questions, eight or nine facts each.
+- `pinecall knowledge eval [GOLDEN] [--base NAME] [--k N]`, and `client.knowledge.eval`: every
+  question of a golden asked of the base, and `recall@k` and `nDCG@10` printed — computed by code
+  with no model, so two runs answer the same numbers. Names every question it missed with what came
+  back instead and exits 1 when anything did, so a base can be held to its golden in CI. Clínica
+  Norte ships one. A base listing now names the embedder that wrote its vectors.
+
+- The package itself: `Pinecall::Agent` (config on the class, state on the instance, `tool` above
+  the method, the comment as the docstring), the ERB view resolved as `views/<slug>.erb`,
+  `Pinecall.mount`, `Pinecall::Client`, and `pinecall/testing` — the gateway that is not there,
+  which is what a ring-0 suite mounts against.
+- The prompt as four named blocks in two regions: `identity` · `knowledge` · `tools` (static,
+  cached), the history, `view` (dynamic). The bridge sends each block by name and only when its
+  text changed. `Pinecall.render` returns `Blocks` (`[:name]`, `static`, `dynamic`,
+  `instructions`); `pinecall prompt` prints one section per block. In a test,
+  `call.block("knowledge")`.
+- `pinecall-protocol`: Ruby's side of the wire, generated from the same JSON Schema as the Python
+  and TypeScript packages, with the log reducer proved against the same golden fixture.
+- `sig/`: the public surface as RBS, checked by `rake rbs`.
+- `examples/clinica_norte`: a whole agent, its view, and its own ring-0 suite.
+- **A lookup is a tool result, never a piece of the prompt.** What memory kept from an earlier
+  call and what the knowledge base returned no longer travel through the view: the platform runs
+  its own `recall` and `search` tools and their answers reach the model as `tool_result` blocks,
+  JSON, in the history — which is where both vendors say content from outside the conversation
+  belongs (`runtime/docs/security/prompt-injection.md`). So a view is now the tenant's own prose
+  and conditions and nothing else: the `memory`, `retrieved` and `knowledge` template tags are
+  gone, and so are the tenant-declared blocks (`prompt static:`/`dynamic:`) and the render props
+  that came with them. What a view may still do with memory is ask it a question —
+  `remembers?("médico habitual")`, answered by the runtime — and say a sentence of its own about
+  the answer.

data/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Pinecall
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,140 @@
+# pinecall
+
+Build voice agents as Ruby classes. Declared fields are the agent's state, `tool` methods are
+what the model can call, the comment above each tool is its description, and an ERB view renders
+the part of the prompt that changes during the call.
+
+```ruby
+require "pinecall"
+
+# Eres la recepción de Clínica Norte. Hablas de usted, con frases cortas.
+class ClinicaNorte < Pinecall::Agent
+  stage :identify, :book
+  state :patient, visibility: :pii
+  state :slots, []
+
+  # Busca al paciente por nombre y teléfono. Pide los dos antes de llamarla.
+  tool stage: :identify, pii: %i[name phone]
+  def find_patient(name:, phone:)
+    self.patient = Agenda.buscar(name, phone)
+    self.stage = :book if patient
+    patient
+  end
+
+  # Horas libres de un día.
+  tool stage: :book, preview: 2
+  def free_slots(day:)
+    self.slots = Agenda.libres(day)
+  end
+end
+```
+
+`views/clinica-norte.erb` renders the prompt from that state:
+
+```erb
+<% if stage == :identify -%>
+Saluda y pide nombre y teléfono. Nada más hasta identificar al paciente.
+<% end -%>
+
+<% if remembers?("médico habitual") -%>
+Ofrece primero las horas de su médico habitual.
+<% end -%>
+
+<% if slots.any? -%>
+## Horas libres, en orden
+
+<% slots.each do |hueco| -%>
+<%= hueco.cuando %> con <%= hueco.doctor %>
+<% end -%>
+<% end -%>
+```
+
+The prompt has four named blocks: `identity`, `knowledge` and `tools` are static and cached
+before the history; `view` comes after it and is replaced every turn. A block is re-sent only when
+its text changes.
+
+Memory and knowledge-base results never enter the prompt. The platform runs `recall` and `search`
+and returns their results to the model as tool results, so retrieved text is treated as data, not
+instructions. A view can ask `remembers?("médico habitual")` and write its own sentence about the
+answer.
+
+## Five minutes
+
+This gem is a library: the verbs are the one `pinecall` CLI's, the same for every language. In a
+project laid out as `agents/<name>/agent.rb`, with this gem in its `Gemfile`:
+
+```bash
+bundle add pinecall
+npm i -g pinecall                     # the CLI: Node, whatever the agent is written in
+pinecall link                         # this folder tied to your org: its key, in ./.env
+pinecall prompt --state test/<name>/goldens/a.json   # the exact prompt a state produces. No gateway.
+pinecall chat                         # the agent served from this terminal, and a caller against it
+pinecall test                         # ring 1: the goldens, scored by the gateway
+pinecall start                        # registered and answering: the process you deploy
+```
+
+The CLI never loads your class: for `prompt`, `chat`, `test` and `start` it runs this gem's serve
+entry, `bundle exec ruby -r pinecall -e 'exit Pinecall::Serve.main(ARGV)'`, and talks to it through
+the gateway. The console, the knowledge bases, memory, keys and every other verb are the CLI's.
+How a server runs the agent, with the CLI or inside your own Ruby process, is
+[docs/production.md](docs/production.md).
+
+## Architecture
+
+This gem is the application side. It never talks to a model vendor or handles audio: it sends
+commands and reads log entries over one WebSocket, in the runtime's own wire (`lib/pinecall/wire/`),
+held to the runtime's golden call log. Tools are the only code that may change state.
+
+| you want | you use |
+|---|---|
+| the class and the view | `Pinecall::Agent`, `Pinecall.mount` |
+| the agent held inside your own process | `Pinecall.serve` |
+| the socket alone, your own way of deciding what to answer | `Pinecall::Client` |
+| a suite with no network, no key and no model | `pinecall/testing` |
+
+```ruby
+pc = Pinecall::Client.new(url: "https://cloud.pinecall.io", api_key: ENV.fetch("PINECALL_KEY"))
+agent = pc.agent("clinica-norte", tools: [])
+agent.on("turn.user") { |data, call| call.say("Le he oído: #{data[:text]}") }
+pc.connect
+```
+
+## Testing it
+
+Agent tests run with no network, key, model or gateway:
+
+```ruby
+require "pinecall/testing"
+
+gateway = Pinecall::Testing::Gateway.new
+Pinecall.mount(ClinicaNorte, client: gateway)
+
+call = gateway.call_started(from: "+34600123456")
+call.tool("free_slots", day: "martes")
+
+assert_includes call.prompt, "el martes a las diez"
+assert_equal %w[propose], call.tools
+```
+
+## Where the rest is
+
+| what | where |
+|---|---|
+| tutorial: an agent with knowledge and memory, from an empty directory | [docs/tutorial.md](docs/tutorial.md) |
+| every file, entity and rule | [ARCHITECTURE.md](ARCHITECTURE.md) |
+| how to write an agent, step by step | [docs/writing-an-agent.md](docs/writing-an-agent.md) |
+| the view, and the blocks of a prompt | [docs/the-view.md](docs/the-view.md) |
+| how to test one | [docs/testing-an-agent.md](docs/testing-an-agent.md) |
+| running it in production | [docs/production.md](docs/production.md) |
+| the CLI, verb by verb | the one CLI's reference, at docs.pinecall.io |
+| a complete example agent | [examples/clinica_norte](examples/clinica_norte) |
+| the wire itself | `lib/pinecall/wire/`, the runtime's shapes this gem speaks |
+
+## Requirements
+
+Ruby 3.2+. The only runtime dependency is `websocket-driver` (the driver ActionCable uses). The
+`pinecall` CLI is a Node program (Node 24+): the verbs need it, the library does not.
+
+## License
+
+[Apache-2.0](LICENSE), including its patent grant. No CLA.

data/lib/pinecall/agent/author.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Pinecall
+  class Agent
+    # Tracks who is writing state, so each write is attributed to its tool or hook.
+    #
+    # Uses fiber storage, not a module variable: concurrent calls must not see each other's author.
+    # `Fiber[]` is inherited by child fibers and separate per thread.
+    module Author
+      KEY = :pinecall_author
+
+      module_function
+
+      # The current author, or nil.
+      def current
+        Fiber[KEY]
+      end
+
+      # Run the block with state writes attributed to `name`.
+      def with(name)
+        held = Fiber[KEY]
+        Fiber[KEY] = name
+        begin
+          yield
+        ensure
+          Fiber[KEY] = held
+        end
+      end
+    end
+  end
+end