The old 10-minute fixed timer caused groups to feel unresponsive after
inactivity. Now uses debounce: timer resets on every new message, flushes
after 5 seconds of quiet. @mentions still flush immediately.
New config: groupDebounceSec (default 5). Old groupPollIntervalMin still
works (converted to ms) for backward compatibility.
Fixes#229
Written by Cameron ◯ Letta Code
"The user is always right. If there is a problem with the use of the system, it's the system that's wrong, not the user." -- Don Norman
- Replace raw JSON parsing with Store class (v1+v2 format support)
- Remove unused listModels import from model.ts
Written by Cameron ◯ Letta Code
"Simplicity is the ultimate sophistication." -- Leonardo da Vinci
- Keep multi-agent normalizeAgents() flow from main
- Integrate deprecation warning for agent.model from PR
- Remove model from LettaBot constructor (server-side property)
- Remove Model: display from single-agent startup log
Written by Cameron ◯ Letta Code
"The best interface is no interface." -- Golden Krishna
editMessage() had no fallback for MarkdownV2 failures (unlike sendMessage
which already falls back to plain text). When the agent generates markdown
tables or other complex formatting, the MarkdownV2 conversion can fail
mid-stream, silently leaving the user with whatever the last successful
streaming edit was -- a truncated message.
Three fixes:
- editMessage() now mirrors sendMessage's try/catch with plain-text fallback
- Final send retry no longer guarded by !messageId, so failed edits fall
back to sending a new complete message
- Streaming edit errors are logged instead of silently swallowed
Written by Cameron ◯ Letta Code
"If you want to go fast, go alone. If you want to go far, go together." - African Proverb
shared.ts was parsing lettabot-agent.json as v1 format directly,
returning null for v2 stores. Now uses the Store class which
handles v1/v2 transparently.
Affects lettabot-message, lettabot-react, and lettabot-history.
Written by Cameron ◯ Letta Code
"Simplicity is the ultimate sophistication." -- Leonardo da Vinci
* Add lettabot-history CLI
* Document and test lettabot-history
* Validate lettabot-history limit
* fix: address review feedback on history CLI
- Extract shared loadLastTarget into cli/shared.ts (was duplicated in message.ts, react.ts, history-core.ts)
- Clamp --limit to platform maximums (Discord: 100, Slack: 1000)
- Fix Discord author formatting: use globalName/username instead of deprecated discriminator
- Add Slack fetch test
Written by Cameron ◯ Letta Code
"You miss 100% of the shots you don't take." -- Wayne Gretzky -- Michael Scott
---------
Co-authored-by: Jason Carreira <jason@visotrust.com>
Co-authored-by: Cameron <cameron@pfiffer.org>
* feat: custom heartbeat prompt via YAML config or file
Wire up the existing but unused HeartbeatConfig.prompt field so users
can customize what the agent sees during heartbeats. Adds three ways
to set it: inline YAML (prompt), file-based (promptFile, re-read each
tick for live editing), and env var (HEARTBEAT_PROMPT). Also documents
the <no-reply/> opt-out behavior.
Fixes#232
Written by Cameron ◯ Letta Code
"The only way to do great work is to love what you do." -- Steve Jobs
* test: add coverage for heartbeat prompt resolution
Tests buildCustomHeartbeatPrompt and HeartbeatService prompt resolution:
- default prompt fallback
- inline prompt usage
- promptFile loading
- inline > promptFile precedence
- live reload (file re-read each tick)
- graceful fallback on missing file
- empty file falls back to default
Written by Cameron ◯ Letta Code
"The only way to do great work is to love what you do." -- Steve Jobs
- Version 0.2.0 (was 1.0.0 -- too early for stable)
- Add files field: only ship dist/, .skills/, patches/
- Add engines: node >= 20
- Add repository, homepage, author metadata
- Add prepublishOnly: build + test gate
- Move patch-package from postinstall to prepare (don't run for end users)
- Add npm publish step to release workflow (requires NPM_TOKEN secret)
- Pre-releases publish with --tag next, stable with --tag latest
- Update release notes install instructions for npm
Closes#174 (once NPM_TOKEN is configured)
Written by Cameron ◯ Letta Code
"Shipping is a feature." -- Jez Humble
normalizeAgents() env var fallback (added in #224) only mapped token
and dmPolicy, missing allowedUsers for all channels. This caused
dmPolicy=allowlist to reject everyone since the allowlist was empty.
Parses *_ALLOWED_USERS env vars (comma-separated) for all five
channels, matching the existing format used by onboard.ts and the
Railway env exporter.
Written by Cameron ◯ Letta Code
"We can only see a short distance ahead, but we can see plenty there that needs to be done." -- Alan Turing
normalizeAgents() only read YAML config, breaking Railway/Docker
deploys where channels are configured via environment variables
(TELEGRAM_BOT_TOKEN, etc.). Add env var fallback in the legacy
single-agent path.
Multi-agent mode still requires YAML configuration.
Written by Cameron ◯ Letta Code
"The cheapest, fastest, and most reliable components are those that aren't there." -- Gordon Bell
* docs: add multi-agent configuration reference
Document the agents[] YAML config, per-agent options, migration path
from single to multi-agent, and known limitations (#219, #220, #221).
Written by Cameron ◯ Letta Code
"Documentation is a love letter that you write to your future self." -- Damian Conway
* docs: fix channels required claim and soften isolation wording
- channels is not strictly required per-agent (validation is global)
- isolation has known exceptions, don't claim "fully isolated"
Written by Cameron ◯ Letta Code
"Clear is kind." -- Brene Brown
When the agent sends a short single-chunk response (e.g. "Yep."), the
streaming edit path sends it to the channel immediately but never sets
sentAnyMessage. When finalizeMessage() then tries to edit the message
to identical content, Telegram rejects it ("message not modified"),
the catch swallows the error, and the post-loop fallback shows a
spurious "(No response)" error alongside the actual reply.
Fix: (1) set sentAnyMessage when the streaming path sends a new message,
(2) treat edit failures as success when messageId exists (the message
is already displayed to the user).
Written by Cameron ◯ Letta Code
"The stream carried everything -- we just forgot to look." - on debugging
Two bugs from the Phase 1 merge:
1. Store not scoped to agent name: LettaBot constructor passed no agent
name to Store, so all agents in multi-agent mode shared the same
agentId/conversationId state. Now passes config.agentName.
2. agentConfig.id ignored: Users could set `id: agent-abc123` in YAML
but it was never applied. Now checked before store verification.
Written by Cameron ◯ Letta Code
"The best error message is the one that never shows up." -- Thomas Fuchs
Multi-agent configs now work end-to-end. Users can write `agents:` in
lettabot.yaml and each agent gets its own channels, cron, heartbeat,
and polling services.
- Rewrite main() to loop over normalizeAgents() output
- Extract createChannelsForAgent() and createGroupBatcher() helpers
- Replace env-var config parsing with YAML-direct for per-agent config
- LettaGateway manages all agents, API server uses gateway for delivery
- Per-agent services: cron, heartbeat, polling are agent-scoped
- Store v2 format handled at startup for LETTA_AGENT_ID loading
- Legacy single-agent configs work unchanged via normalizeAgents()
Part of #109
Written by Cameron ◯ Letta Code
"Make it work, make it right, make it fast." -- Kent Beck
Interface-first multi-agent orchestration layer.
- Define AgentSession interface capturing the contract consumers depend on
- LettaBot implements AgentSession (already has all methods, now explicit)
- LettaGateway manages multiple named AgentSession instances
- Update heartbeat, cron, polling, API server to depend on interface, not concrete class
- 8 new gateway tests
No behavioral changes. Consumers that used LettaBot now use AgentSession interface,
enabling multi-agent without modifying consumer code.
Part of #109
Written by Cameron ◯ Letta Code
"First, solve the problem. Then, write the code." -- John Johnson
* feat: add multi-agent config types, normalizeAgents, and Store v2
Foundation for multi-agent support (Phase 1a). No behavioral changes.
- Add AgentConfig interface for per-agent configuration
- Add agents[] field to LettaBotConfig for docker-compose style multi-agent configs
- Add normalizeAgents() to convert legacy single-agent config to agents[] array
- Evolve Store to v2 format with per-agent state isolation
- Auto-migrate v1 store files to v2 transparently
- 18 new tests for normalization and store migration
Part of #109
Written by Cameron ◯ Letta Code
"The only way to do great work is to love what you do." -- Steve Jobs
* fix: harden multi-agent normalization and store isolation
* style: simplify redundant WhatsApp enabled check
WhatsApp has no credential to check (uses QR pairing), so the
`enabled !== false && enabled` condition simplifies to just `enabled`.
Written by Cameron ◯ Letta Code
"Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." -- Antoine de Saint-Exupery
feat: pass images to the LLM via multimodal API
When users send images through any channel, the actual image content is now passed to the LLM via the SDK's multimodal API (imageFromFile/imageFromURL) instead of just text metadata.
- Graceful fallback for unsupported MIME types, missing files, and load errors
- Opt-out via features.inlineImages: false in config
- Warns when model doesn't support vision (detects [Image omitted] in response)
- Warn at startup when agent.model is present in lettabot.yaml (deprecated, now ignored)
- Add e2e tests for model listing and agent model retrieval
- Remove stale model field from existing e2e test (BotConfig no longer has it)
Written by Cameron ◯ Letta Code
"The best way to predict the future is to invent it." -- Alan Kay
- Document api.port/host/corsOrigin in configuration.md (example,
reference table, and env var mapping)
- Add "Long Messages" section to telegram-setup.md noting the
automatic 4096-char splitting behavior
Written by Cameron ◯ Letta Code
"The best time to plant a tree was 20 years ago. The second best time is now." - Chinese Proverb
Voice messages are now saved to the attachments directory regardless of
transcription outcome. The audio file path is included in the message
envelope so agents always have access to the original audio, even when
transcription fails or returns empty.
🐾 Generated with [Letta Code](https://letta.com)
Co-authored-by: Letta <noreply@letta.com>
* feat: add group message batching, Telegram group gating, and instantGroups
Group Message Batcher:
- New GroupBatcher buffers group chat messages and flushes on timer or @mention
- Channel-agnostic: works with any ChannelAdapter
- Configurable per-channel via groupPollIntervalMin (default: 10min, 0 = immediate)
- formatGroupBatchEnvelope formats batched messages as chat logs for the agent
- Single-message batches unwrapped to use DM-style formatMessageEnvelope
Telegram Group Gating:
- my_chat_member handler: bot leaves groups when added by unpaired users
- Groups added by paired users are auto-approved via group-store
- Group messages bypass DM pairing (middleware skips group/supergroup chats)
- Mention detection for @bot in group messages
Channel Group Support:
- All adapters: getDmPolicy() interface method
- Discord: serverId (guildId), wasMentioned, pairing bypass for guilds
- Signal: group messages bypass pairing
- Slack: wasMentioned field on messages
instantGroups Config:
- Per-channel instantGroups config to bypass batching for specific groups
- For Discord, checked against both serverId and chatId
- YAML config → env vars → parsed in main.ts → Set passed to bot
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: preserve large numeric IDs in instantGroups YAML config
Discord snowflake IDs exceed Number.MAX_SAFE_INTEGER, so YAML parses
unquoted IDs as lossy JavaScript numbers. Use the document AST to
extract the original string representation and avoid precision loss.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: Slack dmPolicy, Telegram group gating check
- Add dmPolicy to SlackConfig and wire through config/env/adapter
(was hardcoded to 'open', now reads from config like other adapters)
- Check isGroupApproved() in Telegram middleware before processing
group messages (approveGroup was called but never checked)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
The watchdog aborted streams after idle timeouts, which breaks legitimate
subagent operations. The SDK stream should throw on connection failures.
Written by Cameron ◯ Letta Code
"The stream will end when it's ready." - a patient engineer
Add a top-level `polling` section to lettabot.yaml for configuring
background polling (Gmail, etc.) instead of relying solely on env vars.
- Add `PollingYamlConfig` type with `enabled`, `intervalMs`, and `gmail` subsection
- Update `configToEnv()` to map new polling config to env vars
- Update `main.ts` to read from YAML config with env var fallback
- Maintain backward compat with `integrations.google` legacy path
- Document polling config in docs/configuration.md
Fixes#201
Co-authored-by: letta-code <248085862+letta-code@users.noreply.github.com>
Co-authored-by: Cameron <cpfiffer@users.noreply.github.com>
Addresses two community-reported issues:
1. Port configuration: The API server port was only readable from the
PORT env var. Add api.port/host/corsOrigin to lettabot.yaml schema
so users can configure it alongside other settings.
2. Telegram sending failures: Messages exceeding Telegram's 4096 char
limit would fail with no splitting. Add splitMessageText() that
splits at paragraph/line boundaries (~3800 chars to leave room for
MarkdownV2 escaping), with a safety net re-split if formatting
expands beyond 4096. Also wrap two unguarded adapter.sendMessage()
calls in bot.ts error paths that could cascade into unhandled
rejections crashing the process.
Written by Cameron ◯ Letta Code
"When you can't make them see the light, make them feel the heat." - Ronald Reagan
The Letta server streams tool_call_message events token-by-token as
the model generates tool arguments. A single tool call (e.g.
memory_rethink with a large new_memory arg) can produce hundreds of
wire events, all sharing the same toolCallId. Without dedup, the bot
miscounts these as separate tool calls -- logging "Calling tool: X"
hundreds of times and potentially triggering the tool-loop abort at
maxToolCalls (default 100) for what is actually a single call.
Track seen toolCallIds per stream and skip chunks already yielded.
Written by Cameron and Letta Code
"In the beginner's mind there are many possibilities, but in the
expert's mind there are few." -- Shunryu Suzuki
The model field in lettabot.yaml was redundant and misleading -- the model
is configured on the Letta agent server-side, and lettabot shouldn't
override it. Users were confused seeing a model in their startup log that
didn't match the actual model being used.
Changes:
- Remove `model` from `LettaBotConfig.agent` (made optional for backward compat)
- Remove `model` from `BotConfig` interface and `bot.ts` createAgent() calls
- Remove `model` from `main.ts` config construction and startup log
- Stop saving `model` to lettabot.yaml during onboarding
- Stop mapping `agent.model` to `MODEL` env var in config/io.ts
- Add `getAgentModel()` and `updateAgentModel()` to letta-api.ts
- Add new `src/commands/model.ts` with three subcommands:
- `lettabot model` - interactive model selector
- `lettabot model show` - show current agent model
- `lettabot model set <handle>` - set model directly
- Wire up model command in cli.ts with help text
- Update docs/configuration.md, lettabot.example.yaml, SKILL.md
Model selection during `lettabot onboard` is preserved for new agent
creation -- the selected model is passed to createAgent() but is NOT
saved to the config file.
Fixes#169
Co-authored-by: Cameron <cpfiffer@users.noreply.github.com>
* feat: add {{NO_REPLY}} silent marker for agent opt-out
Allow the agent to respond with {{NO_REPLY}} to suppress message
delivery for messages that don't warrant a reply. The marker is
checked in three places: the streaming edit guard (prefix match to
prevent partial sends), finalizeMessage(), and the post-stream
response handler.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* refactor: use <no-reply/> XML marker instead of {{NO_REPLY}}
Switch to XML-style self-closing tag for consistency with the XML
envelope format used elsewhere, and because LLMs produce well-formed
XML tags more reliably than template syntax.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add no-reply hint to group chat envelopes
Agents created outside lettabot (via ADE, Letta Cloud) won't have the
system prompt telling them about <no-reply/>. Adding the hint to group
chat envelopes makes the opt-out mechanism self-documenting.
Written by Cameron ◯ Letta Code
"Silence is one of the great arts of conversation." -- Marcus Tullius Cicero
---------
Co-authored-by: Gabriele Sarti <gabriele.sarti996@gmail.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* feat: add ergonomic channel management CLI
Add `lettabot channels` command for easier channel management:
- `lettabot channels` - Interactive menu
- `lettabot channels list` - Show status of all channels
- `lettabot channels add <channel>` - Add with focused setup
- `lettabot channels remove <channel>` - Remove/disable
- `lettabot channels enable/disable <channel>` - Quick toggle
This makes it much easier to add a single channel without going
through the full onboard wizard. For example, adding Discord
after already having Telegram configured now only requires
the Discord-specific prompts.
Also fixes test for /reset command (was added but test not updated).
🐙 Generated with [Letta Code](https://letta.com)
Co-Authored-By: Letta <noreply@letta.com>
* refactor: remove enable/disable commands from channels CLI
Simplify the channels CLI to just add/remove. The enable/disable
commands were redundant - users can use `add` to reconfigure
and `remove` to disable.
🐙 Generated with [Letta Code](https://letta.com)
Co-Authored-By: Letta <noreply@letta.com>
* clean up
---------
Co-authored-by: Letta <noreply@letta.com>
Add `pollIntervalSec` to the Google integration config so the email
polling interval can be set in lettabot.yaml instead of requiring
the POLLING_INTERVAL_MS environment variable.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Add a configurable maxToolCalls safeguard (default: 100) that aborts the
session when the agent enters an infinite tool-calling loop. The stream
watchdog didn't catch this because the stream was active (sending
tool_call events), just not productive.
Configurable via lettabot.yaml:
features:
maxToolCalls: 100
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
The ^6.7.21 caret range resolves to 6.17.16 on fresh npm install, which
ships incompatible TypeScript types (no call signatures on default export).
Pins exact version and adds explicit type annotation on getMessage key param.
Also updates commands.test.ts to expect 5 commands (reset was added but
test still expected 4).
Fixes#192
Written by Cameron ◯ Letta Code
"The caret giveth, and the caret taketh away."
* fix: telegram ESM compatibility and improved diagnostics
- Replace telegram-markdown-v2 with telegramify-markdown (ESM compatible)
- Add raw text fallback when Telegram formatting fails, with error notice
- Improve empty response diagnostics: log agent ID, show conversation ID
- Add reset-conversation command hint to user messages
- Add telegram-format.test.ts with 7 tests
Fixes Railway deployment ERR_REQUIRE_ESM error with remark package.
Written by Cameron and Letta Code
"The best error message is the one that never shows up." - Thomas Fuchs
* fix: add npm overrides for keyv resolution
Users were still hitting ERR_MODULE_NOT_FOUND for keyv even after
PR #154 added it as a direct dependency. This happens because npm's
hoisting doesn't always resolve peer deps of optional deps properly.
npm overrides force the package manager to use our root keyv version
for all nested references, which is the idiomatic solution for
transitive peer dependency issues.
Also adds troubleshooting entry to README.
Written by Cameron ◯ Letta Code
"The best error message is the one that never shows up."
- Thomas Fuchs
When a conversation has an orphaned approval_request_message from a
cancelled/failed run, every subsequent message fails with 409 CONFLICT.
The existing attemptRecovery() can't find these because it checks
agent.pending_approval (null) and scans runs with stop_reason=requires_approval
(but the orphaned run is cancelled/failed).
Adds recoverOrphanedConversationApproval() which directly inspects conversation
messages, finds unresolved approval requests, verifies the originating run is
terminated, and sends denials to clear the stuck state. Both processMessage()
and sendToAgent() now catch CONFLICT errors and retry once after recovery.
Fixes#180
Written by Cameron ◯ Letta Code
"It is not the strongest of the species that survives, nor the most intelligent,
but the one most responsive to change." - Charles Darwin
getPendingApprovals() was calling agents.retrieve() without the
include: ['agent.pending_approval'] parameter, so the Letta API never
returned the pending_approval field. This caused stuck server-side tool
approvals (requires_approval=true) to go undetected, leaving the agent
permanently stuck with empty responses.
Also adds:
- Proactive ensureNoToolApprovals() on startup to disable requires_approval
- /reset slash command for deployed instances (clears conversation, keeps memory)
- Robust parsing for ToolCallDelta and deprecated tool_call field formats
Written by Cameron ◯ Letta Code
"The only way to do great work is to love what you do." - Steve Jobs
The 'ready' event is deprecated in discord.js v14 and will break in v15.
Also switch from on() to once() since this event fires only once per login.
Reported-by: Aeo
Written by Cameron ◯ Letta Code
"The quietest fix is the one that prevents the loudest crash." -- a wise linter
The `if: ${{ secrets.LETTA_API_KEY != '' }}` expression caused a
workflow parse error (secrets can't be used in `if` conditions).
Also `custom_prompt` may not be a valid input for letta-code-action.
Stripped the step for now -- will re-add once letta-code-action
supports release events.
Written by Cameron ◯ Letta Code
"Simplicity is the ultimate sophistication."
- Leonardo da Vinci
Triggers on version tags (v*). Workflow:
1. Builds and runs tests (gate)
2. Generates release notes from merged PRs since last tag
3. Creates GitHub Release (with pre-release detection for alpha/beta/rc)
4. Optionally pings letta-code agent to write a friendly summary
Usage:
git tag v0.1.0
git push origin v0.1.0
Written by Cameron ◯ Letta Code
"Release early, release often."
- Eric S. Raymond
Fixes silent message drops for selfChat users by fixing an
inconsistency between two self-chat detection mechanisms:
1. `isSelfChatMessage()` in utils.ts correctly detects LID-based
self-chat (common on newer WhatsApp versions)
2. `isExtractedSelfChat` in extract.ts only checked `from === selfE164`,
missing LID-based self-chat entirely
When these disagreed, the fromMe filter would pass but the
selfChatMode filter would drop the message silently.
Also adds DEBUG_WHATSAPP=1 environment variable for verbose logging
at all message filter points - helps diagnose similar issues.
Written by Cameron ◯ Letta Code
"Debugging is twice as hard as writing the code in the first place."
- Brian Kernighan
Replace bracket-based message envelopes with XML system-reminder tags
matching Letta Code CLI conventions. The agent already recognizes these
tags, so this standardizes how lettabot sends metadata.
Changes:
- Rewrite formatMessageEnvelope() to use <system-reminder> tags
- Add Session Context section for first message in new chat sessions
- Add Chat Context section (group info, mentions, reply context)
- Move format hints into structured metadata fields
- Export SYSTEM_REMINDER constants and SessionContextOptions
- Update all 36 tests to validate new XML format + add session tests
Closes#170
Written by Cameron ◯ Letta Code
> "The best code is the code that speaks the same language everywhere." - Unknown
- Replace telegram-markdown-v2 with telegramify-markdown (ESM compatible)
- Add raw text fallback when Telegram formatting fails, with error notice
- Improve empty response diagnostics: log agent ID, show conversation ID
- Add reset-conversation command hint to user messages
- Add telegram-format.test.ts with 7 tests
Fixes Railway deployment ERR_REQUIRE_ESM error with remark package.
Written by Cameron and Letta Code
"The best error message is the one that never shows up." - Thomas Fuchs
Users were confused why selfhosted mode still required an API key.
The validation check now properly skips the API key requirement when
server.mode is 'selfhosted'.
Also adds comprehensive selfhosted-setup.md guide covering:
- Letta Docker server setup
- Network configuration (Docker, remote servers)
- Troubleshooting (connection refused, stuck agent, tool approvals)
- Running as a service (systemd, launchd)
- Hardware requirements
Thanks to oculairthebear for the community guide that inspired this.
Written by Cameron and Letta Code
"I've learned that people will forget what you said, people will forget
what you did, but people will never forget how you made them feel."
- Maya Angelou
Changed from unhelpful "(No response from agent)" to more informative
message asking user to try again. Added agent/conversation IDs to logs
for debugging.
Avoids suggesting conversation reset - focuses on retrying.
Written by Cameron ◯ Letta Code
The recovery logic was checking the attempt counter BEFORE checking for
pending approvals. If the counter was >= 2 (from previous failures),
ALL future messages would fail immediately without ever checking if
there were actually pending approvals (which would reset the counter).
Now:
1. Check for pending approvals first
2. If none, reset counter and continue (this was blocked before)
3. Only then check if we've exceeded max attempts
This fixes the case where previous API errors incremented the counter,
but there are no longer any actual pending approvals.
Written by Cameron ◯ Letta Code
* fix: graceful transcription fallback when ffmpeg unavailable
When voice transcription fails (e.g., ffmpeg not installed), the agent
now receives informative error messages instead of silent failures.
Changes:
- transcribeAudio() returns TranscriptionResult with success/error/audioPath
- Tiered fallback: try format rename first, then ffmpeg, then fail gracefully
- Check ffmpeg availability once and cache result
- All channel adapters updated to show transcription errors to agent
- Agent can explain to user why transcription failed
Before:
Agent sees: "[Voice message received]"
Agent: "I received your voice message but there's no content..."
After:
Agent sees: "[Voice message - transcription failed: Cannot transcribe .aac format. Install ffmpeg for audio conversion, or send in a supported format (mp3, ogg, wav, m4a). Audio saved to: /path/to/file.aac]"
Agent: "I couldn't transcribe your voice message because ffmpeg isn't installed. You could type your message instead."
Fixes voice transcription on systems without ffmpeg.
Written by Cameron ◯ Letta Code
"Fail gracefully, inform clearly." - Error handling wisdom
* fix: handle undefined transcription errors better
* fix: correct API param for tool approval + workaround letta-client type bug
