aven-stellar

aven-stellar records a privacy-conscious Git work session for an existing Aven payment stream and submits a structured report to the Aven dashboard. It gives workers a reviewable record of what changed during a work period without running the project or uploading complete source files.

Requirements

• Node.js 20 or newer
• A Git repository
• An existing Aven stream in which the worker is the recipient
• Access to the Aven dashboard and Freighter for the first authorization

Install

Run the CLI without installing it globally:

npx aven-stellar start
npx aven-stellar stop

# Use only for the final project session:
npx aven-stellar stop --ended

When testing a newly published fix, force npx to resolve the current package:

npx --yes aven-stellar@latest --version

If submission failed after a session was stopped, run stop again. The CLI retains the original stop time and retries without adding the delay as work.

Or install both the aven and aven-stellar command aliases globally:

npm install --global aven-stellar
aven start
aven stop

Typical workflow

1. Open a terminal inside the Git repository where the work will happen.
2. Start a session and select the existing Aven stream.
3. Work normally and commit changes when appropriate.
4. Stop the session, review its report, and submit it to the dashboard.

npx aven-stellar start

# Work normally in the repository.

npx aven-stellar stop

On first use, start asks for the dashboard URL and stream ID, then opens the dashboard for wallet authorization. Use http://localhost:3000 when testing against a local Aven server. After authorization it launches a lightweight background activity watcher. stop calculates the Git change statistics, shows the complete report, and asks before submission.

The submitted report appears under WORK SESSIONS on the matching stream page. The worker can request review, and the stream sender can approve or dispute the request.

Command options

npx aven-stellar start --stream <stream-id> --dashboard <url>
npx aven-stellar stop --message <summary>
npx aven-stellar stop --ended

• start --non-interactive skips the collection confirmation.
• stop --submit submits the previewed report without another prompt.
• stop --ended marks the report as the final project session, prompts for the delivery branches, and verifies their head commits against the connected GitHub repository. The dashboard calculates the remaining unreserved escrow and converts it into contract-equivalent seconds before calling the existing verify_work entrypoint. The real npm-tracked active seconds remain in the report.
• --message supplies the worker's summary of the session.
• The payment amount is calculated automatically from tracked active seconds and the stream's on-chain rate, capped by the unreserved escrow remaining.

Privacy and safety

The report includes session timing, the active Git branch, commit metadata, relative changed paths, and additions/deletions. The package creates .avenignore with safe defaults and also respects .gitignore.

The package never:

• requests a Stellar secret key;
• executes project code or tests;
• installs project dependencies;
• records keystrokes or screenshots;
• uploads complete source files; or
• reads paths excluded by .gitignore or .avenignore.

Local, recoverable session state is stored under .aven/. Do not commit that directory.

Automated workers

An AI worker uses the same payment stream and review workflow as a human worker. Once its repository has been authorized, automation can use the non-interactive flags:

npx aven-stellar start --non-interactive
npx aven-stellar stop \
  --message "Implemented the assigned validation changes" \
  --submit

Current enforcement boundary

Work-session payment math is enforced on-chain in the current release. For a normal session, the dashboard verifier reserves exactly active seconds × stream rate, capped by unreserved escrow. For --ended, the server uses ceil(remaining escrow ÷ rate) as the legacy contract's duration argument so the contract caps the verified amount to the exact remaining escrow. This compatibility duration is recorded separately from the real npm active time shown in the report. Pending or reserved session payments must be resolved before a final session can be submitted.

The dashboard asks for explicit client approval on a final session. The currently deployed legacy contract still retains its original timeout-based release rule, so direct on-chain release after that deadline remains possible.

Package development

From this repository:

cd packages/aven-work-session
npm install
npm run typecheck
npm run build

Package page: npmjs.com/package/aven-stellar