portales

Portales

An agent-friendly tool framework that evolves through use.

Portales gives agents a place to build, use, and improve their own tools for external services. Agents explore the real flow, turn what they learn into reusable CLI commands, and repair those commands as services change. They also leave practical guidance for other agents: where to look, which assumptions failed, and how to build and verify tools more efficiently. Each task leaves the next agent with better tools and a better way to work.

portales is a BipBop Labs TypeScript monorepo for integrations that do not have a dependable public API and therefore require browser automation, observed private requests, or both. Service scope includes:

• sii: native Chilean SII authentication, RCV, and electronic-invoicing operations.
• sag: live declaration choices, a private-input preview, and verified receipt downloads; automatic submission is not implemented.
• bci-pyme: BCI's business banking portal.

Service specifications:

• sii: native profile, RCV, and safe DTE invoicing surface.
• sag: public declaration options and dependent border-control/transport catalogs.
• bci-pyme: exact keyring namespace, authentication boundary, browser-session rules, and planned read-only calls.

Setup

Use the pnpm version pinned in package.json. One supported installation path:

git clone https://github.com/BipBop-Labs/portales.git
cd portales
./scripts/install.sh          # pnpm install --frozen-lockfile --prod=false, pnpm run build, symlink ~/.local/bin/portales
portales doctor --json        # local readiness: build, Chromium, Xvfb, pdftotext, keyring, permissions

Update with pnpm run update (git pull --ff-only && pnpm install --frozen-lockfile --prod=false && pnpm run build). pnpm install --frozen-lockfile preserves the locked dependency versions and fails if the manifest and lockfile disagree. Use pnpm update to intentionally refresh dependencies. Portales never updates itself during a portal operation; portales version --json and doctor report a stale build.

Discover capabilities without a profile or a portal:

portales --help
portales sii --help
portales catalog --json
portales describe bci-pyme cartolas download --json

Every result is a versioned envelope (schemaVersion, service, operation, runId, result); errors carry a typed code, the failed stage, nextCommand, and contractRef. Inspect any run afterwards with portales runs show <run-id> and downloads with portales artifacts list.

The native SII service is available through the unified executable:

portales sii auth login --profile default
portales sii rcv summary 2026-09 --profile default
portales sii dte empresas --profile default
portales sii dte emitidos --empresa <rut> --profile default

Status

Discover SAG declaration choices without creating a declaration:

portales sag declaracion-jurada options
portales sag declaracion-jurada preview --input <private-json-file>
portales sag declaracion-jurada --help

The repository implements guarded BCI Pyme operations and native SII authentication, RCV reads, and safe DTE draft/read operations. SII invoice signing and legal issuance remain out of scope.

This is a public repository. Only synthetic examples and fixtures may be committed. Data from users, clients, chats, documents, screenshots, local files, or live portal sessions is never repository material.

The agent owns the full loop: explore the existing code and real flow, run the operation, inspect failures, repair the adapter within repository conventions, update the observed contract, and verify the real result. Capabilities grow from actual use into reusable CLI commands. Follow docs/OPERATIONS.md for diagnostics and repair with the tools currently available.

New work starts with a real useful flow. Add tests only for useful public paths, actual regressions, or identified fragile boundaries. Zero new tests is valid; real portal verification remains the evidence of operational success.

Disclaimer

Unofficial project. Not affiliated with, endorsed by, or supported by the Servicio de Impuestos Internos (SII), Banco de Crédito e Inversiones (BCI), or any other portal operator. Use it only with your own credentials and at your own risk; portal terms of service still apply.

License

MIT, see LICENSE. Portions of services/sii are derived from MIT-licensed work, see services/sii/THIRD_PARTY_LICENSE.md.

Why the name

Portales says what the repository is about without naming a transport. A service may begin as browser automation and later replay an observed request without changing its public identity.

Design in one minute

CLI
 │
 ▼
service task                 stable, JSON-serializable contract
    │
    ▼
service portal module         service-specific navigation and parsing
    │
    ▼
runtime seams                browser, keyring, session, clock, audit, files
    │
    ▼
real portal

• One core task per operation. The CLI is its only maintained public surface.
• Credentials come only from the operating-system keyring. They are never command arguments, environment variables, files, logs, or fixtures.
• Observe the real browser flow before replaying any request.
• Authentication and mutations are never retried automatically.
• JSON is the default machine interface. Human formatting is optional presentation.
• Every portal-defined selector has a CLI options command, so agents can discover valid IDs and labels instead of guessing.
• Shared abstractions are extracted only after a second real service proves the common shape.

Documentation

Agents should read these files in order:

1. AGENTS.md: operating rules and required reading.
2. docs/ARCHITECTURE.md: module boundaries and future tree.
3. docs/RESEARCH-FIRST.md: how to investigate portals safely.
4. docs/CONVENTIONS.md: task, CLI, error, naming, and test contracts.
5. docs/SECURITY.md: credentials, sessions, PII, audit, and write safety.
6. docs/KEYRING.md: exact Secret Service ownership and runtime contract.
7. docs/ADDING-A-SERVICE.md: minimal service workflow and specification template.
8. docs/decisions/README.md: lightweight decision notes, used only when warranted.

Proposed future tree

The tree is a destination, not permission to create empty layers:

apps/
  cli/                         unified `portales` command
packages/
  runtime/                     small, shared seams and Node adapters
services/
  sii/
  sag/
  bci-pyme/
    docs/
      service.md               auth, risks, observed flows, operation catalog
      contracts/               dated portal evidence and wire contracts
    src/
      tasks/                   public operations and guardrails
      portal/                  provider-specific navigation, replay, parsing
    test/
      fixtures/                sanitized, synthetic fixtures only

Do not create a directory until an implemented operation needs it.