freeturtle 0.1.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 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 the 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 the 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 any 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
+
+   Copyright 2025 FreeTurtle Contributors
+
+   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.

package/README.md

@@ -0,0 +1,392 @@
+# FreeTurtle
+
+An open-source framework for deploying autonomous AI CEOs that run onchain businesses.
+
+## Quick Start
+
+```bash
+pnpm install -g freeturtle
+freeturtle init
+freeturtle start
+```
+
+The setup wizard walks you through everything: naming your AI CEO, connecting Farcaster, Telegram, GitHub, a database, and onchain data.
+
+## What It Does
+
+FreeTurtle gives you an autonomous AI CEO that:
+
+- **Posts to Farcaster** on a schedule (or on demand)
+- **Chats with you** via Terminal or Telegram
+- **Writes strategy briefs** weekly
+- **Queries databases** (read-only Postgres)
+- **Creates GitHub issues, writes code and submits pull requests**
+- **Reads onchain data** (balances, contracts, transactions on Base)
+- **Stores identity and memory** as readable Markdown and JSON files
+
+## How It Works
+
+FreeTurtle is a Node.js daemon that mostly sleeps and wakes up when:
+
+1. A **cron timer** fires (e.g. "post to Farcaster every 8 hours")
+2. A **heartbeat** fires (e.g. "check if anything needs attention every 30 minutes")
+3. The **founder sends a message** via Terminal or Telegram
+
+All three route to the same **task runner**, which:
+
+1. Loads `soul.md` (the CEO's identity and voice)
+2. Loads recent memory (posting log, post queue)
+3. Collects tools from active modules
+4. Calls the LLM (Claude or OpenAI)
+5. Checks policy allowlists and approval requirements before executing tools
+6. Handles tool calls in a loop (with automatic retry on transient failures)
+7. Logs every tool call to the audit trail
+8. Persists results to workspace files
+
+```
+┌───────────────────────────────────────────────┐
+│                FreeTurtle Daemon               │
+│                                               │
+│  ┌──────────┐  ┌──────────┐  ┌─────────────┐ │
+│  │ Scheduler │  │ Channels │  │     IPC     │ │
+│  │  (cron)   │  │ Terminal │  │ send/approve│ │
+│  │           │  │ Telegram │  │   /reject   │ │
+│  └─────┬─────┘  └────┬─────┘  └──────┬──────┘ │
+│        │             │               │        │
+│        └──────┬──────┘───────────────┘        │
+│               ▼                               │
+│        ┌──────────────┐                       │
+│        │  Task Runner  │                      │
+│        │  soul + memory│                      │
+│        │  + LLM + tools│                      │
+│        └──────┬───────┘                       │
+│               ▼                               │
+│  ┌─────────────────────────────────────┐      │
+│  │      Policy ─► Approval ─► Retry   │      │
+│  │  allowlists   founder gate  backoff  │      │
+│  └──────────────────┬──────────────────┘      │
+│                     ▼                         │
+│  ┌─────────────────────────────────────┐      │
+│  │            Modules                  │      │
+│  │ Farcaster │ Database│ GitHub│Onchain│      │
+│  └─────────────────────────────────────┘      │
+│                     │                         │
+│               ┌─────▼─────┐                   │
+│               │ Audit Log │                   │
+│               └───────────┘                   │
+└───────────────────────────────────────────────┘
+```
+
+## Modules
+
+### Farcaster
+
+Post and read casts via the Neynar API.
+
+| Tool | Description |
+|------|-------------|
+| `post_cast` | Post a cast, optionally to a channel with embeds |
+| `read_channel` | Read recent casts from a channel |
+| `read_mentions` | Read notifications and mentions |
+| `reply_to_cast` | Reply to a cast by hash |
+| `delete_cast` | Delete a cast (requires founder approval) |
+
+**Env:** `NEYNAR_API_KEY`, `FARCASTER_SIGNER_UUID`, `FARCASTER_FID`
+
+### Database
+
+Query a PostgreSQL database (read-only).
+
+| Tool | Description |
+|------|-------------|
+| `query_database` | Execute a read-only SQL query (SELECT only) |
+| `list_tables` | List all tables with column names and types |
+
+**Env:** `DATABASE_URL`
+
+### GitHub
+
+Create issues, list issues, and commit files.
+
+| Tool | Description |
+|------|-------------|
+| `create_issue` | Create an issue on a repo |
+| `list_issues` | List issues for a repo |
+| `commit_file` | Create or update a file via commit (main branch requires approval) |
+
+**Env:** `GITHUB_TOKEN`
+
+### Onchain
+
+Read smart contracts, balances, and transactions on Base.
+
+| Tool | Description |
+|------|-------------|
+| `read_contract` | Read data from a smart contract |
+| `get_balance` | Get ETH balance of an address |
+| `get_transactions` | Get recent transactions (requires BaseScan key) |
+
+**Env:** `RPC_URL`, `BASESCAN_API_KEY` (optional)
+
+## Configuration
+
+FreeTurtle stores everything in `~/.freeturtle/`:
+
+```
+~/.freeturtle/
+├── soul.md              # CEO identity and voice
+├── config.md            # Modules, cron schedules, LLM settings
+├── .env                 # API keys and secrets
+└── workspace/
+    ├── HEARTBEAT.md     # Heartbeat checklist
+    ├── memory/
+    │   ├── posting-log.json
+    │   ├── post-queue.json
+    │   └── session-notes/
+    ├── audit/           # Daily audit logs
+    ├── approvals/       # Pending/resolved approval requests
+    └── strategy/
+```
+
+### soul.md
+
+Defines who your CEO is — name, voice, knowledge, goals, and boundaries. Written in plain Markdown. Edit it anytime.
+
+### config.md
+
+Controls the daemon. Markdown format:
+
+```markdown
+## LLM
+- provider: claude_api
+- model: claude-sonnet-4-5-20250514
+- max_tokens: 4096
+
+## Cron
+### post
+- schedule: 0 */8 * * *
+- prompt: Check for queued posts. If there's something worth sharing, share it.
+
+### strategy
+- schedule: 0 4 * * 0
+- prompt: Analyze posting history and engagement. Write a strategy brief.
+- output: strategy/{{date}}.md
+
+## Modules
+### farcaster
+- enabled: true
+
+### database
+- enabled: true
+
+## Policy
+### github
+- approval_required_branches: main
+
+### approvals
+- timeout_seconds: 300
+- fail_mode: deny
+```
+
+The setup wizard (`freeturtle setup`) supports five LLM providers: Claude Pro/Max (subscription), ChatGPT Plus/Pro (subscription), Anthropic API, OpenAI API, and OpenRouter.
+
+### .env
+
+API keys. Generated by `freeturtle init`. Never committed to git.
+
+```
+ANTHROPIC_API_KEY=sk-...
+NEYNAR_API_KEY=...
+FARCASTER_SIGNER_UUID=...
+FARCASTER_FID=...
+TELEGRAM_BOT_TOKEN=...
+TELEGRAM_OWNER_ID=...
+GITHUB_TOKEN=...
+DATABASE_URL=postgres://...
+RPC_URL=https://mainnet.base.org
+```
+
+## CLI Commands
+
+```bash
+freeturtle init              # Set up a new AI CEO
+freeturtle start             # Start the daemon
+freeturtle start --chat      # Start with interactive terminal chat
+freeturtle status            # Show daemon status
+freeturtle send "message"    # Send a message to the running CEO
+freeturtle setup             # Reconfigure LLM provider
+freeturtle connect farcaster # Set up Farcaster signer
+freeturtle approvals         # List pending approval requests
+freeturtle approve <id>      # Approve a pending action
+freeturtle reject <id>       # Reject a pending action
+freeturtle update            # Update to the latest version
+freeturtle install-service   # Install as a systemd service (Linux)
+```
+
+## Hosting
+
+We recommend [Oracle Cloud's free ARM instance](docs/oracle-cloud-setup.md) — 4 CPUs, 24 GB RAM, always free. The setup guide walks through account creation, instance setup, networking, and installing FreeTurtle as a system service.
+
+```bash
+# On your server
+pnpm install -g freeturtle
+freeturtle init
+freeturtle start
+freeturtle install-service  # auto-restart on reboot
+```
+
+## Before You Begin
+
+**Create a separate account for your CEO.** Start with a Google account, then use it to sign up for:
+
+- Farcaster (the account your CEO will post from)
+- Neynar (API access for Farcaster)
+- GitHub (if your CEO will manage repos)
+- Any other services your CEO needs
+
+The CEO is effectively a team member who needs its own accounts. Identity separation keeps things clean.
+
+## Policy & Approvals
+
+FreeTurtle enforces per-module allowlists and requires founder approval for destructive actions.
+
+### Policy Config
+
+Add a `## Policy` section to `config.md`:
+
+```markdown
+## Policy
+### github
+- allowed_repos: myorg/myrepo, myorg/other-repo
+- allowed_paths: strategy/, docs/
+- approval_required_branches: main
+
+### farcaster
+- allowed_channels: tortoise, music
+
+### onchain
+- allowed_contracts: 0x1234...
+- allowed_read_functions: balanceOf, totalSupply
+
+### approvals
+- timeout_seconds: 300
+- fail_mode: deny
+```
+
+**Allowlist rules:**
+- Not set → allow all (no restriction)
+- Empty list → deny everything
+- Populated list → only allow listed values
+
+### Approval Flow
+
+Some actions require founder approval before execution:
+
+- `delete_cast` — always requires approval
+- `commit_file` to a protected branch (default: `main`) — requires approval
+
+When approval is needed, FreeTurtle notifies you via Telegram/terminal with the approval ID. You can then:
+
+```bash
+freeturtle approvals          # See pending requests
+freeturtle approve <id>       # Allow the action
+freeturtle reject <id>        # Block the action
+```
+
+If no decision is made within the timeout (default 5 minutes), the action is denied (configurable via `fail_mode`).
+
+### Audit Log
+
+Every task run is logged to `workspace/audit/YYYY-MM-DD/{runId}.json` with:
+- Tool calls made (with redacted inputs)
+- Duration, retries, approval decisions
+- Success/error status
+
+### Reliability
+
+All external API calls (Neynar, GitHub, Postgres, BaseScan, RPC) are wrapped with:
+- Automatic retry with exponential backoff + jitter
+- Timeout protection (30s default)
+- Smart error classification (retry on 429/5xx/network errors, fail fast on 4xx)
+
+## Safety Architecture
+
+FreeTurtle is designed to be safe to run locally:
+
+- **No shell execution** — the CEO cannot run arbitrary commands
+- **Closed tool set** — only the tools defined by enabled modules are available
+- **Policy allowlists** — per-module restrictions on repos, paths, channels, contracts
+- **Founder approval** — destructive actions require explicit approval before execution
+- **Read-only database** — all SQL runs in read-only transactions
+- **Read-only onchain** — no wallet, no signing, no transactions
+- **Founder-only chat** — Telegram only responds to the configured founder ID
+- **Audit trail** — every tool call is logged with redacted inputs
+
+## Security Best Practices
+
+### Secrets
+
+Your `.env` file contains API keys and tokens. FreeTurtle automatically sets it to `chmod 600` (read-only by the file owner) when writing it.
+
+- **Never commit `.env` to git.** It's in `.gitignore` by default — don't override this.
+- **Never paste secrets into AI coding tools.** Tools like Claude Code, Codex, Cursor, and Copilot may log or transmit your input. If an AI tool asks you to paste an API key, token, or recovery phrase into chat — don't. Enter secrets only through FreeTurtle's setup wizard, which writes directly to `.env` on your local machine.
+- **Rotate keys if exposed.** If a secret is accidentally committed, posted, or shared, revoke it immediately and generate a new one. Treat every key as compromised the moment it leaves your machine.
+- **Your Farcaster recovery phrase is the most sensitive secret.** It controls the entire account. FreeTurtle only uses it once during `connect farcaster` to sign a key request locally — it is never stored or transmitted.
+
+### SSH Keys
+
+- Download your SSH private key when creating the instance — you can't retrieve it later
+- Store it securely (e.g. `~/.ssh/`) with `chmod 400`
+- Don't share it or commit it to any repository
+- If lost, you lose access to the server
+
+### Git
+
+- `.env` is in `.gitignore` — don't remove it
+- If you version-control your `~/.freeturtle/` config, exclude `.env`
+- If you accidentally commit secrets, rotate them immediately — git history is permanent
+
+### Firewall
+
+- Oracle Cloud has two firewalls: the cloud security list AND the OS-level iptables
+- Only open ports you actually need
+- SSH (port 22) is open by default — everything else is closed
+- See the [Oracle setup guide](docs/oracle-cloud-setup.md) for details
+
+### Cloud Provider Access
+
+Your cloud provider (Oracle, AWS, GCP) has full access to the underlying infrastructure — they can technically read any file on your VM. This is true of all cloud computing and is covered by their terms of service. For most use cases this is fine. If this is unacceptable for your threat model, run FreeTurtle on hardware you physically control.
+
+## The Two-Turtle Vision (v0.2)
+
+The current v0.1 is a single-process CEO. v0.2 will split it into two:
+
+- **Inner Turtle** — has all the tools, writes to an outbox, never posts directly
+- **Outer Turtle** — reads the outbox, reviews actions, executes approved ones
+
+This creates **security by architecture, not by instruction**. The inner turtle can reason freely without risk because it literally cannot post or commit — only propose. The outer turtle is a simple approval layer.
+
+This pattern, proven by tortOS, means you can give your CEO powerful tools without worrying about rogue actions.
+
+## tortOS — Proof of Concept
+
+FreeTurtle generalizes the patterns proven by [tortOS](https://tortoise.xyz), which runs the Tortoise music platform on Farcaster/Base:
+
+- Autonomous posting and community engagement
+- Weekly strategy briefs
+- Database queries for platform analytics
+- GitHub issue management
+- All controlled by a soul config and readable memory files
+
+tortOS has been running autonomously for months. FreeTurtle packages those patterns into a framework anyone can use.
+
+## Roadmap
+
+- **v0.1** — Single-process CEO (this release)
+- **v0.2** — Two-turtle architecture (inner/outer split, outbox, approval queue)
+- **v0.3** — XMTP integration (public-facing DMs)
+- **Future** — Hosted dashboard, multi-CEO management
+
+## License
+
+Apache 2.0 — see [LICENSE](./LICENSE).

package/dist/bin/freeturtle.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};