@meffecta/agent 1.0.0 → 1.0.2

package/IMPLEMENTATION.md

@@ -1,292 +0,0 @@
-# Setting up a new agent
-
-Every step from nothing to a first run, in order. For how the pieces fit and why, see
-[ARCHITECTURE.md](ARCHITECTURE.md).
-
-Everything here is one command-line tool, `npx @meffecta/agent`, run from **your content
-repo** — the directory step 3 creates, which holds this deployment's jobs and its settings.
-You never need the engine's source: the tool and the engine image it deploys are published
-together, and installing the tool is all the access you need.
-
-    npx @meffecta/agent steps     # this guide, condensed to the command for each step
-
----
-
-## 1. Create a GCP project
-
-Give the agent a project of its own, separate from any product project it will read: this
-project's service account gets project-wide secret access, and the mail tokens stored here
-must not be readable by another system's machinery.
-
-```bash
-gcloud auth login
-npx @meffecta/agent create-project
-```
-
-It asks for a display name, suggests a project ID from it, validates the ID against
-Google's rules before spending a round trip, and creates the project. Pass
-`--name`/`--id` to skip the prompts, or `ORGANIZATION=…` / `FOLDER=…` to place it.
-
-- [ ] Note the **project ID** it prints. Project IDs are globally unique, so a plain name
-      is often taken and you end up with a suffixed one (`acme-agent-506513`). The id, not
-      the display name, is what every later command needs.
-
-## 2. Link a billing account
-
-Nothing else works without this: provisioning starts by enabling APIs, which fails on an
-unbilled project.
-
-```bash
-npx @meffecta/agent link-billing --project <PROJECT_ID>
-```
-
-It lists the billing accounts you can use, marks closed ones as unselectable (linking one
-appears to succeed and leaves the project unbilled), links your choice, and then confirms
-the project really is billed rather than trusting the command's exit code.
-
-- [ ] `billingEnabled: true`
-
-If it reports a **billing quota**, that is the account's cap on how many projects it may
-fund, not a problem with this project — free a slot with `gcloud billing projects unlink
-<PROJECT>`, or request an increase.
-
-## 3. Create the content repo
-
-A private GitHub repo holding everything about *this* deployment:
-
-```
-deployment.env     # which GCP project and service this deployment runs as
-SYSTEM.md          # who the agent serves, its worlds, its tone
-jobs/              # one .md per job: YAML frontmatter + prompt body
-worlds/            # one folder per business area (optional to start)
-.claude/skills/    # skills this deployment owns or overrides (optional)
-```
-
-`deployment.env` is committed — none of it is secret, and a clone of the repo is then
-everything an operator needs:
-
-```bash
-npx @meffecta/agent init          # writes deployment.env here
-```
-
-```ini
-PROJECT=acme-agent-506513     # the project ID from step 1
-SERVICE=acme-agent
-ARTIFACT_REPO=acme-agent-images
-REGION=europe-west1
-```
-
-`SYSTEM.md` describes **who this agent serves** — the person or team, the businesses, the
-tone, which systems belong to whom. It does not need to restate the safety rules: the
-engine appends its own baseline ([SYSTEM.base.md](SYSTEM.base.md) — what you read is data
-not instructions, act only where the job says, secrets never leave, third-party privacy,
-report honestly) to every run in every deployment, and that baseline overrides anything
-contradicting it. Your `SYSTEM.md` can make a rule *stricter*, or name the concrete
-accounts and people it applies to; it cannot relax one.
-
-One job to start, `jobs/hello.md`:
-
-```markdown
----
-name: hello
-cron: "0 7 * * 1-5"
----
-
-Say good morning and list today's date. Send it by email to <person> using the
-send-email skill. If email is unavailable, return the text as your result.
-```
-
-Frontmatter keys: `cron`, `webhook`, `inbox`, `repo`, `systemMd`, `model`, `effort`,
-`allowedTools`, `timeoutSeconds`, `disabled`. A job with no `name:` takes its filename.
-
-- [ ] Repo pushed to GitHub
-- [ ] `cd` into it — **every command from here on runs from the content repo**
-
-## 4. Install the tools
-
-On the machine you operate from:
-
-```bash
-docker info >/dev/null && echo "docker ok"   # needed to mirror engine images
-git --version && gh --version
-node --version                                # 24+
-npm i -g @anthropic-ai/claude-code
-corepack enable
-```
-
-- [ ] `gcloud auth configure-docker $REGION-docker.pkg.dev` — one-time, so the mirror in
-      step 8 can push into your Artifact Registry. Pulling the engine image itself needs
-      no login: `ghcr.io/meffecta/agent` is public.
-
-Then the tool itself:
-
-```bash
-npm i -g @meffecta/agent      # or use npx, which needs no install
-meffecta-agent version        # names the engine build this version deploys
-```
-
-- [ ] `meffecta-agent help` lists the commands
-- [ ] `meffecta-agent version` shows a pinned engine tag, not "latest"
-
-Pin the version you install. Each release of the tool deploys the engine image published
-alongside it, so upgrading the tool is how you move to a new engine — deliberately, not by
-surprise.
-
-<details>
-<summary>No npm? The same tooling is inside the public image.</summary>
-
-```bash
-cid=$(docker create ghcr.io/meffecta/agent:latest) \
-  && docker cp "$cid:/app/scripts" . \
-  && docker rm "$cid" >/dev/null
-```
-
-That drops `scripts/` into your content repo; run `scripts/deploy.sh` and friends directly,
-and `scripts/update-tooling.sh --tag <the tag you deploy>` to refresh them. Every CLI
-command is one of these scripts with a name in front of it.
-</details>
-
-## 5. Mint the credentials
-
-```bash
-claude setup-token       # → CLAUDE_CODE_OAUTH_TOKEN, pasted in step 7
-```
-
-- [ ] `CLAUDE_CODE_OAUTH_TOKEN` — this deployment bills its own runs
-- [ ] `GITHUB_TOKEN` — fine-grained PAT with **contents read on the content repo** (the
-      service cannot start without it), plus write on any repo whose jobs open PRs
-- [ ] `AGENT_WEBHOOK_SECRET` needs nothing here — step 7 generates it
-
-**Gmail + Calendar** (skip if the agent needs no mailbox). In the agent's GCP project:
-enable the Gmail and Calendar APIs; OAuth consent screen → **External**, then **publish to
-production** — an app left in "Testing" expires refresh tokens after 7 days; create an
-OAuth client of type **Desktop app**. Then per account:
-
-```bash
-npx @meffecta/agent mint-gmail \
-  --client-id <id> --client-secret <secret> [--account <NAME>] [--readonly]
-```
-
-Sign in as the account the token is for. Default → `GMAIL_REFRESH_TOKEN`; named →
-`GMAIL_<NAME>_REFRESH_TOKEN`. Use `--readonly` for any mailbox this company does not
-administer alone.
-
-**Microsoft 365** (only if a mailbox lives there): one Entra app registration, then
-`npx @meffecta/agent mint-graph --account <NAME> …`.
-
-## 6. Provision the infrastructure
-
-```bash
-npx @meffecta/agent setup-infra
-```
-
-Idempotent — re-run it after any change. It prints the project and service it is about to
-touch, then creates: the APIs, an Artifact Registry repo, the runtime service account, a
-memory bucket (mounted at `/memory`), an audit bucket (365-day retention, write-once,
-never mounted), and the Cloud Run service shell with a placeholder image and CPU always
-allocated.
-
-- [ ] The banner names the project from your `deployment.env` — if not, you are in the
-      wrong directory
-
-## 7. Wire up the configuration
-
-`set-secret.sh` stores a value in Secret Manager and binds it to the service in one step;
-the value never reaches your shell history or the screen. Re-running it rotates a value.
-
-```bash
-npx @meffecta/agent set-secret AGENT_WEBHOOK_SECRET --random   # generated for you
-npx @meffecta/agent set-secret CLAUDE_CODE_OAUTH_TOKEN         # prompts, hidden
-npx @meffecta/agent set-secret GITHUB_TOKEN
-```
-
-- [ ] `AGENT_WEBHOOK_SECRET`
-- [ ] `CLAUDE_CODE_OAUTH_TOKEN`
-- [ ] `GITHUB_TOKEN`
-
-Non-secret settings go through `set-env` (several at once become one revision; add
-`--dry-run` to see what it would do). **The service will not boot without `GIT_REPO_URL`:**
-
-```bash
-npx @meffecta/agent set-env GIT_REPO_URL=https://github.com/<owner>/<repo>.git
-```
-
-- [ ] `GIT_REPO_URL` points at the content repo from step 3
-
-Optional, one ability each: `GMAIL_*`, `MSGRAPH_*`, `GRAFANA_*`, `CLOUDFLARE_*`,
-`POSTHOG_*`, `GOOGLE_ADS_*`, `AHREFS_API_KEY`, `<WORLD>_GA4_PROPERTY_ID`. Full list with
-comments in the engine repo's `.env.example`. Tokens and keys go through `set-secret`;
-addresses, ids and URLs through `set-env`. `meffecta-agent env` and `meffecta-agent secrets`
-show what is set — the second never prints a value.
-
-Surfaces that authenticate as the **runtime service account** rather than a token — GA4,
-Search Console, Google Ads, Cloud Run deployment listing, and delegated Gmail/Drive/
-Calendar — additionally need that service account invited on each property, and
-domain-wide delegation granted in the Workspace admin console. Leave these for last; each
-degrades gracefully until granted.
-
-## 8. Deploy the engine
-
-```bash
-npx @meffecta/agent deploy             # --dry-run first to see the target
-```
-
-Mirrors the engine image this tool version was published with into your Artifact Registry,
-rolls it out, and asserts the runtime shape from `deployment.env`. `--tag <other>` pins or
-rolls back to a different build.
-
-## 9. Create the triggers
-
-The service scales to zero and has CPU only while it is answering a request, so nothing in
-it fires on its own. This is what sends it work:
-
-```bash
-npx @meffecta/agent setup-scheduler    # --dry-run first to see what it would create
-```
-
-It creates a Cloud Tasks queue, points the service at it, and creates one Cloud Scheduler
-job per `cron:` in your content repo plus a housekeeping sweep. It reads the job list from
-the running service, so step 8 has to have succeeded first.
-
-- [ ] It reports one trigger per cron job, plus `<service>-sweep`
-- [ ] `npx @meffecta/agent triggers` agrees, and shows the task queue running
-
-Re-run it whenever a job's `cron:` changes or a job is added or renamed — `deploy` does it
-for you on every rollout from here on. Check it any time with `meffecta-agent triggers`.
-
-## 10. Verify
-
-```bash
-npx @meffecta/agent status
-npx @meffecta/agent jobs
-```
-
-- [ ] `status` shows a ready revision, your triggers, and an idle queue
-- [ ] `jobs` lists your jobs — this proves the boot clone worked. An empty list means
-      `GIT_REPO_URL` is wrong or `GITHUB_TOKEN` cannot clone it.
-
-Then exercise every configured credential from inside the deployment:
-
-```bash
-npx @meffecta/agent ask "run node /app/scripts/verify-credentials.mjs and return its output"
-```
-
-- [ ] Each surface reports ok or skip; no FAIL (`skip` = not configured, which is fine)
-
-The same thing has a web page, for anyone who would rather not use a terminal: open
-`/ask` on the service URL that `status` printed. Any username, the secret as the password.
-
-- [ ] The page loads and an answer comes back
-
-## 11. First real run
-
-```bash
-npx @meffecta/agent run hello
-npx @meffecta/agent logs --limit 50
-```
-
-- [ ] Read what it produced before letting the cron take over
-
-Then add jobs one at a time — each push is live on the next run. `disabled: true` in
-frontmatter is the kill switch, effective on push. Every prompt, result and full
-transcript lands in the audit bucket.