# Dehook agent workflow, version 1

Service: https://dehook.me. This guide describes the hosted API, not an instruction to install a new server or runtime.

## Bind one project to one app

1. Inspect the existing project, its instructions and Dehook configuration. Reuse its runtime and HTTP client. Do not install Node.js, Veloce, a framework, or a local server just to use Dehook.
2. Prefer the credential file supplied by the owner. Landing-page downloads contain schemaVersion, server, publicToken and privateToken. Compare publicToken with the identity in the owner's prompt and any existing project binding. Stop on a mismatch and ask which app to use.
3. Before saving credentials, add `/.dehook/` to .gitignore. Keep the private file at `.dehook/credentials.json`, directory mode 0700 and file mode 0600. Never put it in chat, logs, source, screenshots, exported functions, or committed configuration. Existing configured clients also contain private credentials and belong in this ignored directory.
4. Track `dehook/config.json` with schemaVersion 1, server and publicToken only. Track function sources in `dehook/functions/<name>.js`. Merge a short reference to this workflow and those paths into an existing project AGENTS.md; preserve its other instructions.
5. Missing credentials for an existing binding are not a reason to create a new app. Ask the owner for the file path. Never guess, rotate, or replace credentials automatically.

If the owner explicitly requests a NEW app and no binding exists, use an atomic provisioning lock and POST /token once. Save env[0] immediately in the private file and bind its publicToken. Do not provision per agent, branch, restart, or failed request. Creation has no idempotency key: an ambiguous network failure requires reconciliation with the owner, not a blind retry. Browser creation requires the dehook.me origin; existing server-side tools can call it without an Origin header.

For a claimed backend, ask the owner to download a deploy key from https://dehook.me/account. It uses the same private credential file format. Claiming disables the previous anonymous private token; do not mint a replacement backend when that token stops working.

## Publish and verify

Use HTTPS and JSON request bodies. Read credentials from the file at runtime, never from command-line arguments. Use the project's existing HTTP library; no jq pipelines or exported environment variables are required.

1. POST /app/usage with the flat credential pair to check identity/access and available budget. Stop if the credentials fail.
2. Write a named synchronous JavaScript function to a tracked file. A first smoke test can be:

```javascript
function hello(data) {
  return { response: "Hello " + String(data.name) + "!" };
}
```

3. POST /data-processor/{publicToken}/hello with:

```json
{"token":{"publicToken":"FROM_FILE","privateToken":"FROM_FILE"},"script":"FUNCTION_FILE_CONTENTS"}
```

Check HTTP success AND `status: "success"`. This overwrites the named function, so inspect existing source before replacing a function not created for this task. POST /exports/{publicToken} returns the public source map.

4. POST /process/{publicToken}/hello with `{"data":{"name":"Ada"}}`. Assert `response` equals `Hello Ada!`. Running public functions does not require a private token.
5. Read usage again. Report the public app identity, function name, expected/actual result and changed files. Never report the private token. Reuse the same binding on the next run.

The public API contract is at https://dehook.me/assets/agents/v1/contract.json.

## Execution and data boundaries

Functions run synchronously in isolated Veloce workers. Do not return promises or assume async/await, network access, host filesystem access, processes, dependency installation, or raw database/ORM access. Use the built-in scoped query/session APIs. Approved native helpers include crypto, YAML and numeric kernels; consult https://dehook.me/docs for supported methods. External calls requiring secrets belong in the project's existing trusted runtime.

Exported function SOURCE IS PUBLIC to holders of the public token. The public token identifies the app, it is not user authentication. Add application authorization before exposing private data through a callable function. Private tokens grant publishing and direct document access. Never embed them in a shared browser application.

New free apps: 8 KiB serialized documents/sessions, 6 KiB serialized function map, bounded metadata, 16 KiB total logical state. At most 16 documents, 2 KiB per document (including generated fields), 3 functions, 2 KiB source each, 8 KiB execution reply. JavaScript deadline 500 ms with a 1-second outer worker deadline. Limits are server-enforced and may be tightened. Existing larger data can be exported or shrunk, not grown.

Admission is limited per app, IP and globally. A free app currently has 1000 requests/day, 30 executions/minute, one concurrent execution and bounded daily reply bytes/runtime. Creation also has strict IP/global caps. A 429 is not a reason to make another app. Honor Retry-After with bounded backoff where retrying is safe. Do not blindly retry token creation, rotation, query writes, or function executions: the previous operation may already have happened. Publishing identical source to the same name can be retried after checking its outcome.

Do not bypass quotas, split data across newly minted apps, delete data to make a test pass, weaken permissions, or change VPS configuration. Token rotation and deletion require an explicit owner instruction. POST /app/export accepts the flat credential pair for recovery, including when ordinary app admission is exhausted; recovery still has separate quotas.