@baldaworks/balda-linux-arm64 0.3.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,308 @@
+# balda
+
+[![test](https://github.com/baldaworks/balda/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/baldaworks/balda/actions/workflows/test.yml)
+[![lint](https://github.com/baldaworks/balda/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/baldaworks/balda/actions/workflows/lint.yml)
+
+## Self-hosted engineering agent for team chat
+
+Balda is a self-hosted engineering agent that lives in your team chat and works
+inside your project.
+
+You can give it a task in chat, open a focused topic for a piece of work, run a
+longer goal loop, or wire external events into the same workflow. Balda keeps
+context, uses your configured tools, and returns something reviewable: a
+summary, changed files, validation output, a commit, or a concrete next step.
+
+## What Balda is good for
+
+- chat-native engineering help in Telegram, Zulip, or Slack
+- focused task threads instead of one shared bot conversation
+- long-running goal execution with progress updates and final results
+- `wedge` style operation: put the agent in the middle of your team workflow so
+  chat, tools, schedules, and external events all feed the same execution path
+- self-hosted deployment close to your repo, config, and credentials
+
+## Quickstart
+
+You need:
+
+- one chat surface: Telegram, Zulip, or Slack
+- one supported provider CLI installed on the host or in Docker:
+  `codex`, `opencode`, `copilot`, `gemini`, or `claude`
+- Node.js/npm, unless you run the Docker Compose path
+
+Install:
+
+```bash
+npm install -g -y @baldaworks/balda
+```
+
+Initialize in your project:
+
+```bash
+balda init
+```
+
+Start:
+
+```bash
+balda start
+```
+
+`balda init` creates `.config/balda/config.yaml`, initializes
+`.config/balda/state.db`, detects available provider CLIs, and prints the next
+step for your selected chat provider.
+
+## First run
+
+For Telegram, authenticate the owner with the command printed by `balda init`:
+
+```text
+/start owner=<owner_token>
+```
+
+Then send a normal direct message to the bot, or open an isolated topic:
+
+```text
+/topic release
+```
+
+From there you can:
+
+- ask for ordinary help in chat
+- start a goal loop with `/goalkeeper <objective>`
+- stop the current turn with `/cancel`
+- reset the current session with `/reset`
+
+## Main workflows
+
+### 1. Ordinary chat work
+
+Send a message in the session where you want work to happen. Balda keeps that
+conversation as the execution context.
+
+### 2. Focused topic work
+
+Use `/topic <name>` to create a separate session for a task, incident, release,
+or stream of work.
+
+### 3. Goal-driven execution
+
+Use `/goalkeeper <objective>` when you want Balda to keep working until there is a
+result to review.
+
+Balda will:
+
+- work in repeated passes
+- post progress updates
+- ask follow-up questions when critical input is missing
+- return a terminal result with outcome details
+
+See [docs/goal-workflow.md](docs/goal-workflow.md) for the detailed goal
+contract.
+
+### 4. Wedge mode
+
+Balda can act as a wedge between team chat and the rest of your engineering
+system:
+
+- chat messages start work
+- scheduled jobs wake work up
+- inbound webhooks turn external events into session work
+- the same session can continue through follow-up questions and delayed work
+
+This is useful when you want one operational path for human requests,
+automation, and agent execution instead of separate bots and scripts.
+
+## Supported chat providers
+
+- Telegram
+- Zulip
+- Slack
+
+Balda maps each conversation scope to its own session:
+
+- Telegram direct chat or personal/group topic
+- Zulip stream + topic
+- Slack thread
+
+## Docker Compose
+
+Balda ships a root [Dockerfile](Dockerfile) and [compose.yaml](compose.yaml)
+for local Docker Compose deployment.
+
+The current directory is mounted as `/workspace`, so Balda sees your checkout,
+config, git metadata, and local state.
+
+```bash
+docker compose build balda
+docker compose run --rm balda init
+docker compose up -d balda
+```
+
+Polling mode is the default, so Telegram does not require publishing a port.
+Webhook deployment details live in [docs/balda.md](docs/balda.md).
+
+## Published container image
+
+Balda publishes a release image at `ghcr.io/baldaworks/balda:latest`.
+
+That image contains the `balda` binary only. It does not bundle provider CLIs.
+Use it as a source stage in your own image and add the provider runtime you
+want.
+
+Example with Codex:
+
+```dockerfile
+FROM node:24-bookworm-slim AS cli-builder
+RUN npm install -g @openai/codex
+
+FROM ghcr.io/baldaworks/balda:latest AS balda
+
+FROM node:24-bookworm-slim
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      ca-certificates \
+      git \
+      openssh-client \
+      ripgrep \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY --from=cli-builder /usr/local/lib/node_modules /usr/local/lib/node_modules
+COPY --from=cli-builder /usr/local/bin/codex /usr/local/bin/codex
+COPY --from=balda /usr/local/bin/balda /usr/local/bin/balda
+
+WORKDIR /workspace
+ENTRYPOINT ["balda"]
+```
+
+## Core commands
+
+- `/start owner=<owner_token>` — owner bootstrap in direct messages
+- `/start invite=<invite_token>` — collaborator onboarding
+- `/topic <name>` — open a focused session
+- `/goalkeeper <objective>` — run a longer goal loop
+- `/goalkeeper clear` — stop active goal work in the current session
+- `/cancel` — stop the current turn
+- `/reset` or `/restart` — clear the current session and start fresh
+- `/locator` — show the current session locator for scheduler/webhook routing
+
+Full command behavior is documented in [docs/balda.md](docs/balda.md).
+
+## Configuration
+
+Balda loads `.config/balda/config.yaml` and then applies `BALDA_*` environment
+overrides. If a local `.env` exists, Balda loads it before resolving config.
+
+Minimal shape:
+
+```yaml
+runtime:
+  providers:
+    codex:
+      type: codex_acp
+      codex_acp: {}
+  mcp_servers: {}
+
+balda:
+  provider: codex
+  telegram:
+    token: ""
+```
+
+Common settings:
+
+- `balda.provider` — which configured provider runtime to use
+- `balda.telegram.token` — Telegram bot token
+- `balda.telegram.formatting_mode` — Telegram output mode: `rich_markdown`
+  (default), `rich_html`, or `none` for literal plain text
+- `balda.zulip.*` — Zulip outgoing webhook bot credentials and receiver config
+- `balda.slack.*` — Slack bot token, signing secret, and HTTP receiver config
+- `balda.webhooks.*` — optional inbound webhook routes
+- `balda.scheduler.jobs` — recurring scheduled jobs
+- `balda.workspace.*` — workspace/worktree behavior for goal execution
+- `balda.permissions.mode` — agent permission policy: `allow_all`, `ask`, or `deny_all`
+- `balda.permissions.timeout` — maximum wait for an interactive permission decision (default `2m`)
+- `balda.memory.enabled` — enable the global explicit-fact memory store and its
+  bundled MCP tools (default `true`)
+- `balda.mcp_servers` — MCP servers injected into Balda-started sessions
+
+### Explicit fact memory
+
+The bundled `balda.memory.remember` tool stores explicit facts globally for the
+Balda instance. Each update records a latest-memory timestamp. On a subsequent
+session turn, Balda compares that timestamp with the turn's memory cursor. When
+they differ, Balda adds the complete current fact-memory snapshot to that same
+provider user prompt in a delimited application-memory block. Unchanged, empty,
+or disabled memory adds nothing to the prompt. Global fact memory is expected to
+remain small; it is separate from optional durable session memory.
+
+### Knowl sidecar
+
+Run [Knowl](https://github.com/baldaworks/knowl) separately, then register its
+MCP endpoint through Balda's existing generic configuration:
+
+```yaml
+runtime:
+  mcp_servers:
+    knowl:
+      type: http
+      url: http://127.0.0.1:8080/mcp
+
+balda:
+  mcp_servers:
+    - knowl
+```
+
+This exposes `knowl_retrieve`, `knowl_ingest`, and `knowl_operation` to
+Balda-started sessions. Balda does not start Knowl, initialize its workspace,
+own its provider/storage configuration, or automatically ingest conversation
+turns.
+
+`allow_all` preserves historical behavior and should be used only where every
+agent tool call is trusted. Production chat deployments should normally set
+`BALDA_PERMISSIONS_MODE=ask`; unsupported channels, missing requester context,
+cancellation, and timeout fail closed.
+
+Set `BALDA_TELEGRAM_FORMATTING_MODE` to override the Telegram mode. Existing
+`markdownv2` configurations must move to `rich_markdown` (or `none`), and
+existing `html` configurations must move to `rich_html` (or `none`). Balda does
+not accept compatibility aliases: an unsupported value fails startup before
+ingress begins accepting messages. See the
+[Telegram formatting guide](docs/telegram-formatting.md) for rollout and
+fallback details.
+
+For complete configuration, examples, and provider-specific details, see
+[docs/balda.md](docs/balda.md).
+
+## Troubleshooting
+
+- `telegram token is required` — run `balda init` or set
+  `BALDA_TELEGRAM_TOKEN`
+- `no supported agent CLI detected` — install or expose one of `codex`,
+  `opencode`, `copilot`, `gemini`, or `claude`
+- `balda.provider is required` — rerun `balda init` or set a configured
+  provider id manually
+- webhook or Slack/Zulip startup issues — verify the matching `balda.*`
+  integration settings in config
+- workspace import/export issues — check `balda.workspace.mode`,
+  `balda.workspace.base_branch`, and the git checkout Balda is running in
+
+## Docs
+
+- Product and operator docs: [docs/balda.md](docs/balda.md)
+- Goal workflow: [docs/goal-workflow.md](docs/goal-workflow.md)
+- Architecture map: [docs/architecture/index.md](docs/architecture/index.md)
+- Telegram formatting: [docs/telegram-formatting.md](docs/telegram-formatting.md)
+- Zulip webhook setup: [docs/zulip-webhook.md](docs/zulip-webhook.md)
+- Slack setup: [docs/slack.md](docs/slack.md)
+- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Release
+
+- GitHub Releases: <https://github.com/baldaworks/balda/releases>
+- npm package: <https://www.npmjs.com/package/@baldaworks/balda>
+
+npm releases are published from Git tags through the Omnidist workflow. The
+`NPM_PUBLISH_TOKEN` repository secret must have permission to publish the public
+`@baldaworks/balda` package in the `baldaworks` npm organization.

package/package.json

@@ -0,0 +1,20 @@
+{
+  "bin": {
+    "balda": "bin/balda"
+  },
+  "cpu": [
+    "arm64"
+  ],
+  "description": "@baldaworks/balda binary for linux/arm64",
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "name": "@baldaworks/balda-linux-arm64",
+  "os": [
+    "linux"
+  ],
+  "version": "0.3.0"
+}