eve 0.90.0 → 0.91.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +34 -23
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/sandbox/bash.js +2 -2
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/admission.d.ts +6 -0
- package/dist/src/execution/session/admission.js +1 -1
- package/dist/src/execution/session/delivery-facts.js +1 -1
- package/dist/src/execution/session/next-input.d.ts +2 -2
- package/dist/src/execution/session/next-input.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
- package/dist/src/execution/session-inbox/inbox.js +1 -1
- package/dist/src/execution/session-inbox/protocol.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/compaction/engine.js +2 -2
- package/dist/src/harness/current-messages.js +1 -1
- package/dist/src/harness/emission.d.ts +3 -0
- package/dist/src/harness/emission.js +1 -1
- package/dist/src/harness/facts.d.ts +5 -2
- package/dist/src/harness/facts.js +1 -1
- package/dist/src/harness/model-call/call.d.ts +7 -1
- package/dist/src/harness/model-call/call.js +3 -1
- package/dist/src/harness/provider-tool-history.d.ts +8 -0
- package/dist/src/harness/provider-tool-history.js +1 -1
- package/dist/src/harness/session-machine/transitions.d.ts +3 -2
- package/dist/src/harness/step/after-model.js +1 -1
- package/dist/src/harness/step/context.js +1 -1
- package/dist/src/harness/step/intake.js +1 -1
- package/dist/src/harness/step/prompt.js +1 -1
- package/dist/src/harness/tool-history-repair.d.ts +2 -0
- package/dist/src/harness/tool-history-repair.js +1 -1
- package/dist/src/harness/tool-loop.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
- package/dist/src/protocol/session-events/families/delivery.js +1 -1
- package/dist/src/protocol/session-projection/fold.js +1 -1
- package/dist/src/public/channels/discord/hitl.js +1 -1
- package/dist/src/public/channels/slack/hitl.d.ts +2 -1
- package/dist/src/public/channels/slack/hitl.js +3 -3
- package/dist/src/public/channels/slack/interaction-cards.js +1 -1
- package/dist/src/public/channels/slack/request-card-render.js +1 -1
- package/dist/src/public/channels/teams/hitl.js +1 -1
- package/dist/src/public/channels/teams/verify.js +1 -1
- package/dist/src/public/definitions/hook.d.ts +90 -7
- package/dist/src/public/definitions/hook.js +1 -1
- package/dist/src/public/hooks/index.d.ts +3 -2
- package/dist/src/reactions/continuation.d.ts +19 -0
- package/dist/src/reactions/continuation.js +1 -0
- package/dist/src/reactions/intents.d.ts +10 -4
- package/dist/src/reactions/intents.js +1 -1
- package/dist/src/reactions/kinds/hook.js +1 -1
- package/dist/src/reactions/runner.js +1 -1
- package/dist/src/reactions/state.d.ts +15 -2
- package/dist/src/reactions/state.js +1 -1
- package/dist/src/runtime/resolve-connection.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/primitives/open-url.js +1 -1
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tools/provided/web-fetch.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +264 -281
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -206
- package/docs/channels/github.mdx +24 -22
- package/docs/channels/linear.mdx +30 -30
- package/docs/channels/linq.mdx +25 -13
- package/docs/channels/mcp.mdx +154 -116
- package/docs/channels/overview.mdx +31 -32
- package/docs/channels/photon.mdx +32 -56
- package/docs/channels/slack.mdx +538 -375
- package/docs/channels/teams.mdx +40 -26
- package/docs/channels/telegram.mdx +13 -13
- package/docs/channels/twilio.mdx +11 -11
- package/docs/code-extension.mdx +40 -42
- package/docs/concepts/built-in-tools.md +89 -57
- package/docs/concepts/context-control.md +20 -20
- package/docs/concepts/default-harness.md +20 -36
- package/docs/concepts/execution-model-and-durability.mdx +96 -160
- package/docs/concepts/project-structure.mdx +21 -14
- package/docs/concepts/security-model.md +27 -27
- package/docs/concepts/sessions-runs-and-streaming.md +184 -198
- package/docs/concepts/state.md +7 -15
- package/docs/connections/mcp.mdx +109 -93
- package/docs/connections/openapi.mdx +57 -59
- package/docs/connections/overview.mdx +175 -170
- package/docs/evals/assertions.mdx +36 -29
- package/docs/evals/cases.mdx +38 -42
- package/docs/evals/judge.mdx +21 -29
- package/docs/evals/overview.mdx +42 -38
- package/docs/evals/reporters.mdx +54 -27
- package/docs/evals/running.mdx +15 -8
- package/docs/evals/targets.mdx +16 -19
- package/docs/evals/tool-stubs.mdx +111 -97
- package/docs/experimental/dynamic-schedules.mdx +118 -63
- package/docs/extensions.md +58 -65
- package/docs/getting-started.mdx +4 -6
- package/docs/guides/auth-and-route-protection.md +87 -70
- package/docs/guides/client/continuations.mdx +23 -26
- package/docs/guides/client/messages.mdx +47 -66
- package/docs/guides/client/output-schema.mdx +8 -8
- package/docs/guides/client/overview.mdx +45 -43
- package/docs/guides/client/streaming.mdx +62 -71
- package/docs/guides/decide.md +24 -79
- package/docs/guides/deployment/meta.json +1 -1
- package/docs/guides/deployment/overview.md +27 -18
- package/docs/guides/deployment/self-hosted-operations.md +99 -0
- package/docs/guides/deployment/self-hosting.md +63 -80
- package/docs/guides/deployment/vercel.mdx +31 -27
- package/docs/guides/deployment/workflow-worlds.md +100 -0
- package/docs/guides/dev-tui.md +48 -41
- package/docs/guides/dynamic-capabilities.md +49 -50
- package/docs/guides/frontend/nextjs.mdx +2 -2
- package/docs/guides/frontend/nuxt.mdx +11 -11
- package/docs/guides/frontend/overview.mdx +1 -1
- package/docs/guides/frontend/sveltekit.mdx +11 -11
- package/docs/guides/frontend/tanstack.mdx +16 -16
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
- package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
- package/docs/guides/frontend/use-eve-agent.mdx +25 -25
- package/docs/guides/hooks.md +152 -106
- package/docs/guides/instrumentation/agent-runs.mdx +26 -30
- package/docs/guides/instrumentation/instrumentation.mdx +49 -76
- package/docs/guides/instrumentation/meta.json +1 -1
- package/docs/guides/instrumentation/otel.mdx +113 -179
- package/docs/guides/remote-agents.md +125 -187
- package/docs/guides/self-modification.md +18 -18
- package/docs/guides/session-context.md +16 -16
- package/docs/install-integrations.mdx +26 -24
- package/docs/instructions.mdx +37 -42
- package/docs/memory/custom-provider.md +35 -41
- package/docs/memory/file.md +93 -76
- package/docs/memory/overview.mdx +145 -156
- package/docs/patterns/durable-cross-channel-notifications.md +15 -19
- package/docs/patterns/dynamic-scheduling.md +19 -23
- package/docs/patterns/multi-tenant-approvals.md +17 -22
- package/docs/patterns/multi-tenant-auth.md +43 -42
- package/docs/patterns/multi-tenant-memory.md +39 -36
- package/docs/patterns/voice-notes.md +3 -3
- package/docs/protocols/acp.md +13 -13
- package/docs/protocols/ucp.mdx +7 -7
- package/docs/reference/agent-files.md +6 -6
- package/docs/reference/cli.md +99 -98
- package/docs/reference/telemetry.md +1 -1
- package/docs/reference/typescript-api.md +52 -53
- package/docs/responsible-use.md +2 -2
- package/docs/sandbox/custom-providers.mdx +60 -56
- package/docs/sandbox/default.mdx +23 -24
- package/docs/sandbox/docker.mdx +16 -10
- package/docs/sandbox/index.mdx +93 -61
- package/docs/sandbox/just-bash.mdx +17 -11
- package/docs/sandbox/troubleshooting.mdx +29 -23
- package/docs/sandbox/vercel.mdx +45 -52
- package/docs/schedules.mdx +65 -54
- package/docs/skills.mdx +74 -49
- package/docs/subagents/index.mdx +97 -136
- package/docs/tools/human-in-the-loop.md +160 -90
- package/docs/tools/meta.json +1 -1
- package/docs/tools/overview.mdx +229 -237
- package/docs/tools/tasks.md +118 -117
- package/docs/tools/workflows.mdx +447 -543
- package/docs/tutorial/connect-a-warehouse.mdx +11 -13
- package/docs/tutorial/first-agent.mdx +14 -16
- package/docs/tutorial/guard-the-spend.mdx +6 -8
- package/docs/tutorial/how-it-runs.mdx +8 -8
- package/docs/tutorial/query-sample-data.mdx +8 -8
- package/docs/tutorial/remember-definitions.mdx +4 -4
- package/docs/tutorial/run-analysis.mdx +20 -22
- package/docs/tutorial/ship-it.mdx +19 -19
- package/docs/tutorial/team-playbooks.mdx +9 -9
- package/docs/use-cases.mdx +13 -11
- package/package.json +1 -1
- package/docs/guides/instrumentation/migration.md +0 -96
- package/docs/tools/tasks-upgrade.md +0 -218
package/docs/channels/github.mdx
CHANGED
|
@@ -4,7 +4,9 @@ description: "Reach your agent from GitHub App webhooks, with comment invocation
|
|
|
4
4
|
type: integration
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
The GitHub channel lets
|
|
7
|
+
The GitHub channel lets people reach your agent from issues and pull requests. It lives in `agent/channels/github.ts`. Write the agent's invocation token, such as `@my-agent`, in a new issue, PR, or review comment, and the agent replies in that thread. It sees the PR diff and works in a checkout of the repo.
|
|
8
|
+
|
|
9
|
+
[Vercel Connect](../guides/auth-and-route-protection) can manage the GitHub App, its token, and webhook checks, so you hold no private key or webhook secret. See [Channels](./overview) for what all channels share.
|
|
8
10
|
|
|
9
11
|
## Guided Connect setup
|
|
10
12
|
|
|
@@ -14,11 +16,7 @@ Run the registry setup from the agent directory:
|
|
|
14
16
|
eve add channel/github
|
|
15
17
|
```
|
|
16
18
|
|
|
17
|
-
The
|
|
18
|
-
|
|
19
|
-
Vercel Connect creates the GitHub App, receives and verifies its webhooks, and forwards them to the deployed agent. After deploying, open the GitHub App in the Connect dashboard and install it in the organization or account where you want to use it. Add the generated invocation token (for example, `@my-agent`) to a new issue, pull request, or review comment to start a conversation. GitHub may not autocomplete the token or render it as a linked mention.
|
|
20
|
-
|
|
21
|
-
The generated channel uses Connect-managed credentials:
|
|
19
|
+
The command signs you in to Vercel, links a project, and creates an app-scoped GitHub Connect client that sends webhooks to `/eve/v1/github`. It then installs `@vercel/connect` and writes the channel file:
|
|
22
20
|
|
|
23
21
|
```ts title="agent/channels/github.ts"
|
|
24
22
|
import { connectGitHubCredentials } from "@vercel/connect/eve";
|
|
@@ -30,11 +28,11 @@ export default githubChannel({
|
|
|
30
28
|
});
|
|
31
29
|
```
|
|
32
30
|
|
|
33
|
-
|
|
31
|
+
Connect creates the GitHub App and forwards its webhooks, and eve checks their Vercel OIDC signature. Connect also handles token rotation and multiple installations. After you deploy, open the GitHub App in the Connect dashboard and install it in your organization or account.
|
|
34
32
|
|
|
35
33
|
### Bring your own GitHub App
|
|
36
34
|
|
|
37
|
-
To run a GitHub App you manage yourself, pass its credentials directly
|
|
35
|
+
To run a GitHub App you manage yourself, pass its credentials directly:
|
|
38
36
|
|
|
39
37
|
```ts title="agent/channels/github.ts"
|
|
40
38
|
import { githubChannel } from "eve/channels/github";
|
|
@@ -49,7 +47,7 @@ export default githubChannel({
|
|
|
49
47
|
});
|
|
50
48
|
```
|
|
51
49
|
|
|
52
|
-
|
|
50
|
+
Omit any field, or the whole `credentials` block, to read it from these env vars:
|
|
53
51
|
|
|
54
52
|
```bash
|
|
55
53
|
GITHUB_APP_ID=... # GitHub App id
|
|
@@ -58,17 +56,19 @@ GITHUB_WEBHOOK_SECRET=... # verifies the webhook signature
|
|
|
58
56
|
GITHUB_APP_SLUG=... # supplies botName when it is not set in config
|
|
59
57
|
```
|
|
60
58
|
|
|
61
|
-
`appId
|
|
59
|
+
`appId`, `privateKey`, `webhookSecret`, and `botName` also accept a function. A `botName` function runs when a webhook arrives, so it can use that request's credentials. eve keeps its result, or tries again on the next event if it fails. Omit `botName` to use the credentials' `appSlug`, then `GITHUB_APP_SLUG`.
|
|
62
60
|
|
|
63
|
-
Point the GitHub App webhook URL at `https://<deployment>/eve/v1/github`.
|
|
61
|
+
Point the GitHub App webhook URL at `https://<deployment>/eve/v1/github`. Subscribe to `issue_comment` and `pull_request_review_comment` so comments reach the agent. Add `issues`, `pull_request`, `check_suite`, `check_run`, or `workflow_run` for their opt-in hooks. Install the App on the repository, and a new comment that includes `@botName` starts a turn.
|
|
62
|
+
|
|
63
|
+
The invocation token is plain text, not a GitHub mention, so GitHub may not autocomplete or link `@botName`. GitHub may show the App as `botName[bot]`.
|
|
64
64
|
|
|
65
65
|
## How the channel handles messages
|
|
66
66
|
|
|
67
67
|
### Dispatch
|
|
68
68
|
|
|
69
|
-
|
|
69
|
+
Each hook returns `{ auth }` to start a turn or `null` to ignore the event. Add `title` to set the run title when the event starts a run. `defaultGitHubAuth(ctx)` builds auth from the person who triggered the event.
|
|
70
70
|
|
|
71
|
-
The model
|
|
71
|
+
The model sees a `<github_context>` block with `sender` and, when known, `bot_name`. For comments it also has `is_mentioned`, which eve sets before it removes the invocation token from the text.
|
|
72
72
|
|
|
73
73
|
```ts
|
|
74
74
|
import { defaultGitHubAuth, githubChannel } from "eve/channels/github";
|
|
@@ -93,37 +93,39 @@ export default githubChannel({
|
|
|
93
93
|
});
|
|
94
94
|
```
|
|
95
95
|
|
|
96
|
-
The CI hooks expose normalized `action`, `status`, `conclusion`, `app.slug`, `headSha`, and `pullRequests` fields, plus `checkSuiteId`, `checkRunId`, or `workflowRunId`. `workflow_run
|
|
96
|
+
The CI hooks expose normalized `action`, `status`, `conclusion`, `app.slug`, `headSha`, and `pullRequests` fields, plus `checkSuiteId`, `checkRunId`, or `workflowRunId`. For `workflow_run`, which only GitHub Actions sends, `app.slug` is `"github-actions"`. A CI turn replies on the first PR in `pullRequests`. When the array is empty, the hook still runs but must return `null`, because there is no thread to reply in.
|
|
97
97
|
|
|
98
98
|
### Delivery
|
|
99
99
|
|
|
100
|
-
When a turn starts, the channel adds an `eyes` reaction to the
|
|
100
|
+
When a turn starts, the channel adds an `eyes` reaction to the comment that triggered it. Set `progress: { reactions: false }` to skip it. The reply posts as a comment on the timeline or in the review thread, split across several comments when long. A failed turn posts a short error comment with an error id.
|
|
101
101
|
|
|
102
102
|
### Human-in-the-loop (HITL)
|
|
103
103
|
|
|
104
|
-
GitHub comments have no
|
|
104
|
+
GitHub comments have no buttons or cards, so an approval or question posts as a comment. The user answers it with a reply comment. Declare an `events["interaction.opened"]` handler to change the prompt.
|
|
105
105
|
|
|
106
106
|
### Proactive sessions
|
|
107
107
|
|
|
108
|
-
|
|
108
|
+
To start a session without a comment, call `to(github, target).send(message, { auth })` from a schedule's `run` handler. From another channel, call `ctx.to(github, target).send(message, { auth })`. The target needs `owner`, `repo`, and exactly one of `issueNumber` or `pullRequestNumber`. This sends a message to the agent, not a comment to GitHub.
|
|
109
109
|
|
|
110
|
-
To post without invoking the model, use `ctx.channel.thread.post(...)` inside a GitHub event handler.
|
|
110
|
+
To post without invoking the model, use `ctx.channel.thread.post(...)` inside a GitHub event handler. To retry and deduplicate notifications across providers yourself, see [Durable cross-channel notifications](../patterns/durable-cross-channel-notifications).
|
|
111
111
|
|
|
112
112
|
### Attachments
|
|
113
113
|
|
|
114
|
-
|
|
114
|
+
The channel doesn't accept inbound file attachments. Repository contents reach the agent through the [sandbox checkout](#sandbox-checkout).
|
|
115
115
|
|
|
116
116
|
### PR context
|
|
117
117
|
|
|
118
|
-
|
|
118
|
+
On a PR, the agent always gets the PR metadata and the patch of each changed file in `context`. Large generated files stay in the file list without their patch. Add more paths to skip with `pullRequestContext.excludedFiles`.
|
|
119
119
|
|
|
120
120
|
### Sandbox checkout
|
|
121
121
|
|
|
122
|
-
Before the first model call,
|
|
122
|
+
Before the first model call, each turn checks out the repo into the sandbox. `read_file`, `glob`, `grep`, and `bash` then work on the real files.
|
|
123
|
+
|
|
124
|
+
The installation token never enters the sandbox, because the sandbox firewall adds auth to outbound `git` requests. Checkout needs a sandbox with a firewall (Vercel), so the local sandbox skips it.
|
|
123
125
|
|
|
124
126
|
### Arbitrary API calls
|
|
125
127
|
|
|
126
|
-
For
|
|
128
|
+
For any other GitHub API call, use `ctx.github.request({ method, path, body })`. It sends the installation token.
|
|
127
129
|
|
|
128
130
|
## What to read next
|
|
129
131
|
|
package/docs/channels/linear.mdx
CHANGED
|
@@ -4,7 +4,9 @@ description: "Reach your agent through Linear Agent Sessions, with native Agent
|
|
|
4
4
|
type: integration
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
The Linear channel
|
|
7
|
+
The Linear channel lets people delegate issues to your agent, or mention it, in Linear. It lives in `agent/channels/linear.ts` and uses Linear Agent Sessions. The agent shows its progress and answers as native Agent Activities: `thought`, `action`, `elicitation`, `response`, and `error`.
|
|
8
|
+
|
|
9
|
+
[Vercel Connect](../guides/auth-and-route-protection) can manage the Linear app, its token, and webhook checks, so you hold no API key or webhook secret. See [Channels](./overview) for what all channels share.
|
|
8
10
|
|
|
9
11
|
## Guided Connect setup
|
|
10
12
|
|
|
@@ -20,11 +22,7 @@ To let the agent search and update Linear through MCP, install the separate Line
|
|
|
20
22
|
eve add connection/linear
|
|
21
23
|
```
|
|
22
24
|
|
|
23
|
-
The channel
|
|
24
|
-
|
|
25
|
-
Vercel Connect creates the Linear app with the `app:assignable` and `app:mentionable` scopes required for Agent Sessions, receives and verifies `AgentSessionEvent` webhooks, and forwards them to the deployed agent. After deploying, open the Linear app in the Connect dashboard and install it in the workspace where you want to delegate work. Then delegate an issue or mention the agent in a Linear Agent Session.
|
|
26
|
-
|
|
27
|
-
The generated channel uses Connect-managed credentials:
|
|
25
|
+
The channel command signs you in to Vercel, links a project, and reuses or creates an app-scoped Linear Connect client that sends webhooks to `/eve/v1/linear`. It then installs `@vercel/connect` and writes the channel file:
|
|
28
26
|
|
|
29
27
|
```ts title="agent/channels/linear.ts"
|
|
30
28
|
import { connectLinearCredentials } from "@vercel/connect/eve";
|
|
@@ -35,11 +33,11 @@ export default linearChannel({
|
|
|
35
33
|
});
|
|
36
34
|
```
|
|
37
35
|
|
|
38
|
-
|
|
36
|
+
Connect creates the Linear app with the `app:assignable` and `app:mentionable` scopes that Agent Sessions require. Connect forwards the app's webhooks, and eve checks their Vercel OIDC signature. Connect also handles token rotation and multiple workspaces. After you deploy, open the Linear app in the Connect dashboard and install it in your workspace. Then delegate an issue or mention the agent.
|
|
39
37
|
|
|
40
38
|
### Bring your own Linear app
|
|
41
39
|
|
|
42
|
-
To run a Linear OAuth app you manage yourself, pass its credentials directly
|
|
40
|
+
To run a Linear OAuth app you manage yourself, pass its credentials directly:
|
|
43
41
|
|
|
44
42
|
```ts title="agent/channels/linear.ts"
|
|
45
43
|
import { linearChannel } from "eve/channels/linear";
|
|
@@ -52,14 +50,12 @@ export default linearChannel({
|
|
|
52
50
|
});
|
|
53
51
|
```
|
|
54
52
|
|
|
55
|
-
Direct webhook verification accepts timestamps within 60 seconds by default, as Linear recommends. Set `maxSkewMs` to a larger number of milliseconds only when you intentionally accept delayed retries. Use the narrowest window that fits your retry policy.
|
|
56
|
-
|
|
57
53
|
```bash
|
|
58
54
|
LINEAR_AGENT_ACCESS_TOKEN=lin_api_... # posts Agent Activities and creates proactive sessions
|
|
59
55
|
LINEAR_WEBHOOK_SECRET=... # verifies Linear-Signature
|
|
60
56
|
```
|
|
61
57
|
|
|
62
|
-
|
|
58
|
+
Omit `credentials` to read the access token from `LINEAR_AGENT_ACCESS_TOKEN`, `LINEAR_ACCESS_TOKEN`, `LINEAR_API_KEY`, or `LINEAR_API_TOKEN`. The webhook secret then comes from `LINEAR_WEBHOOK_SECRET`. Both fields also accept a function.
|
|
63
59
|
|
|
64
60
|
Create the Linear OAuth app, enable Agent Session events, and point the webhook URL at:
|
|
65
61
|
|
|
@@ -67,39 +63,45 @@ Create the Linear OAuth app, enable Agent Session events, and point the webhook
|
|
|
67
63
|
https://<deployment>/eve/v1/linear
|
|
68
64
|
```
|
|
69
65
|
|
|
70
|
-
|
|
66
|
+
Configure the OAuth authorize URL with `actor=app` and grant the scopes that let the app appear as an agent, including `app:assignable` and `app:mentionable`. Subscribe to the `AgentSessionEvent` webhook category. Linear then sends `created` when someone delegates to or mentions the agent, and `prompted` when the user replies.
|
|
67
|
+
|
|
68
|
+
eve checks the `Linear-Signature` HMAC over the raw body. It rejects a `webhookTimestamp` older than 60 seconds, as Linear recommends. Raise `maxSkewMs` (milliseconds) only to accept delayed retries, and keep it as small as your retry policy allows.
|
|
71
69
|
|
|
72
|
-
|
|
70
|
+
If a trusted gateway verifies Linear webhooks first, pass `credentials.webhookVerifier` instead of a webhook secret. `maxSkewMs` doesn't apply to a verifier, so the verifier must check timestamps itself.
|
|
73
71
|
|
|
74
72
|
## How the channel handles messages
|
|
75
73
|
|
|
76
74
|
### Dispatch
|
|
77
75
|
|
|
78
|
-
|
|
76
|
+
By default, `created` and `prompted` Agent Session events start a turn. The model sees the agent session, issue, comment, and organization ids, plus `app_user_id` when known. Each Linear Agent Session maps to one eve session, keyed `agent-session:<id>`.
|
|
79
77
|
|
|
80
78
|
### Delivery
|
|
81
79
|
|
|
82
|
-
Turn
|
|
80
|
+
| Turn event | Agent Activity |
|
|
81
|
+
| ----------------------- | -------------------------------------------------- |
|
|
82
|
+
| Turn starts | Ephemeral `thought` |
|
|
83
|
+
| Text before a tool call | Ephemeral `thought`, from its first non-empty line |
|
|
84
|
+
| Tool call | Ephemeral `action` |
|
|
85
|
+
| Final assistant text | `response`, not ephemeral |
|
|
86
|
+
| Failure | `error` |
|
|
83
87
|
|
|
84
88
|
### Human-in-the-loop (HITL)
|
|
85
89
|
|
|
86
|
-
|
|
90
|
+
Approvals and questions post as `elicitation` activities. The user's reply in the Agent Session answers the open one, and the turn continues.
|
|
87
91
|
|
|
88
92
|
### Connection authorization
|
|
89
93
|
|
|
90
|
-
When a
|
|
91
|
-
|
|
92
|
-
### Proactive sessions
|
|
93
|
-
|
|
94
|
-
Start a session without an inbound webhook with `receive(linear, { target })`. See [Proactive sessions](#proactive-sessions) below for the target shape and examples.
|
|
94
|
+
When a connection needs the user to sign in, the channel posts Linear's native `auth` elicitation with the provider's sign-in URL. It goes to the user who started the session. A device flow without a URL posts its instructions and user code as a plain elicitation. When sign-in ends, the channel posts a `thought` with the result, and a successful sign-in continues the turn.
|
|
95
95
|
|
|
96
96
|
### Attachments
|
|
97
97
|
|
|
98
|
-
|
|
98
|
+
Markdown images (``) and file links (`[name](url)`) in an Agent Session prompt reach the model as files. This works only for links to `https://uploads.linear.app`, which eve downloads with the Linear access token. eve sends the token only to that exact HTTPS origin, and links to other hosts stay Markdown text.
|
|
99
|
+
|
|
100
|
+
A file fails when the download fails, an image link returns non-image content, or a file link returns an HTML page. The link then becomes its label, and the agent gets a note that the file couldn't be retrieved. The turn continues.
|
|
99
101
|
|
|
100
102
|
### API handle
|
|
101
103
|
|
|
102
|
-
Event handlers receive `channel.linear
|
|
104
|
+
Event handlers receive `channel.linear`. Use its `createActivity`, `listActivities`, and `updateSession` methods to post your own Agent Activities and update the Agent Session.
|
|
103
105
|
|
|
104
106
|
### Low-level API helpers
|
|
105
107
|
|
|
@@ -114,7 +116,7 @@ channel context's API handle when it already has the configured credentials.
|
|
|
114
116
|
|
|
115
117
|
## Custom hooks
|
|
116
118
|
|
|
117
|
-
Return `{ auth }` to
|
|
119
|
+
Return `{ auth }` to start a turn, or `null` to accept the webhook without waking the agent. Add `title` to set the run title when the event starts a run.
|
|
118
120
|
|
|
119
121
|
```ts
|
|
120
122
|
import { defaultLinearAuth, linearChannel } from "eve/channels/linear";
|
|
@@ -127,7 +129,7 @@ export default linearChannel({
|
|
|
127
129
|
});
|
|
128
130
|
```
|
|
129
131
|
|
|
130
|
-
|
|
132
|
+
To restrict the agent to some Linear teams or projects, inspect `event.agentSession.issue`. Return `context` alongside `auth` to add background:
|
|
131
133
|
|
|
132
134
|
```ts
|
|
133
135
|
import { defaultLinearAuth, linearChannel } from "eve/channels/linear";
|
|
@@ -143,7 +145,7 @@ export default linearChannel({
|
|
|
143
145
|
});
|
|
144
146
|
```
|
|
145
147
|
|
|
146
|
-
Override event
|
|
148
|
+
Override event handlers to post your own Agent Activities:
|
|
147
149
|
|
|
148
150
|
```ts
|
|
149
151
|
import { linearChannel } from "eve/channels/linear";
|
|
@@ -167,7 +169,7 @@ export default linearChannel({
|
|
|
167
169
|
});
|
|
168
170
|
```
|
|
169
171
|
|
|
170
|
-
Add session
|
|
172
|
+
Add session links when your agent creates an external artifact:
|
|
171
173
|
|
|
172
174
|
```ts
|
|
173
175
|
await channel.linear.updateSession({
|
|
@@ -177,7 +179,7 @@ await channel.linear.updateSession({
|
|
|
177
179
|
|
|
178
180
|
## Proactive sessions
|
|
179
181
|
|
|
180
|
-
|
|
182
|
+
To start a session without a webhook, call `to(linear, target).send(message, { auth })`. The target continues an existing Agent Session by `agentSessionId`, or creates one from an `issueId` or root `commentId`. This example runs from a schedule; a route handler passes the same target to `ctx.to(...)`.
|
|
181
183
|
|
|
182
184
|
```ts
|
|
183
185
|
import { defineSchedule } from "eve/schedules";
|
|
@@ -199,8 +201,6 @@ export default defineSchedule({
|
|
|
199
201
|
});
|
|
200
202
|
```
|
|
201
203
|
|
|
202
|
-
For issue or comment targets, the channel calls Linear's proactive Agent Session mutations before starting the eve turn. For an existing `agentSessionId`, it skips session creation and only seeds the continuation token.
|
|
203
|
-
|
|
204
204
|
## What to read next
|
|
205
205
|
|
|
206
206
|
- [Channels overview](./overview): the channel contract and every built-in channel
|
package/docs/channels/linq.mdx
CHANGED
|
@@ -3,9 +3,9 @@ title: Linq
|
|
|
3
3
|
description: Connect an eve agent to iMessage and SMS through Linq.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
The Linq channel connects your agent to iMessage and SMS conversations through `agent/channels/linq.ts`.
|
|
7
7
|
|
|
8
|
-
Run `eve add channel/linq`
|
|
8
|
+
Run `eve add channel/linq` and choose Vercel Connect or portable credentials. With Vercel Connect, eve signs you in and links a Vercel project. It then asks whether to create a managed Linq account and line, or connect an existing account with its partner API token. You select the account's phone numbers for the agent, and eve configures the connector and webhook through Connect:
|
|
9
9
|
|
|
10
10
|
```ts title="agent/channels/linq.ts"
|
|
11
11
|
import { connectLinqCredentials } from "@vercel/connect/eve";
|
|
@@ -16,13 +16,13 @@ export default linqChannel({
|
|
|
16
16
|
});
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
The
|
|
19
|
+
The channel receives webhooks at `/eve/v1/linq` and, by default, verifies them with Vercel OIDC from the same project and environment. It builds auth from the person who sent each message, marks accepted messages as read, and keeps one eve session per Linq conversation.
|
|
20
20
|
|
|
21
|
-
Set `turnPolicy: "queue"`
|
|
21
|
+
A message that arrives during a turn joins that turn, so the agent can take the correction into account. Set `turnPolicy: "queue"` to let every reply finish before the next message starts. See [Overlapping messages](./overview#overlapping-messages) for when a new message can interrupt the model.
|
|
22
22
|
|
|
23
|
-
Images and other files people send reach the agent as file parts. eve downloads each one
|
|
23
|
+
Images and other files people send reach the agent as file parts. eve downloads each one over HTTPS. Downloads and redirects must resolve to public network addresses and time out after 30 seconds. A failed download, or a file over 25 MB, reaches the agent as a short note instead.
|
|
24
24
|
|
|
25
|
-
Customize inbound
|
|
25
|
+
Customize inbound handling with `onMessage`. Return `null` to ignore a message, or return `title` alongside `auth` to set the run title when the message starts a run:
|
|
26
26
|
|
|
27
27
|
```ts
|
|
28
28
|
export default linqChannel({
|
|
@@ -37,7 +37,7 @@ export default linqChannel({
|
|
|
37
37
|
});
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
Set `route` to
|
|
40
|
+
Set `route` to change the webhook path, or `webhookVerifier` (typed `LinqWebhookVerifier` from `eve/channels/linq`) to use a different trusted-forwarder verifier. A verifier receives the request and its raw body bytes. It rejects a webhook by throwing or returning a falsy value such as `null` or `false`.
|
|
41
41
|
|
|
42
42
|
## Tapbacks
|
|
43
43
|
|
|
@@ -60,7 +60,15 @@ export default linqChannel({
|
|
|
60
60
|
});
|
|
61
61
|
```
|
|
62
62
|
|
|
63
|
-
|
|
63
|
+
| Field | Value |
|
|
64
|
+
| ------------------- | ---------------------------------------------------------------------------------------------- |
|
|
65
|
+
| `tapback.tapback` | `love`, `like`, `dislike`, `laugh`, `emphasize`, `question`, or the emoji for an emoji tapback |
|
|
66
|
+
| `tapback.messageId` | The message the tapback is on |
|
|
67
|
+
| `tapback.author` | The person who sent it |
|
|
68
|
+
|
|
69
|
+
The agent reads an accepted tapback as iMessage's text form, such as `Tapback: Loved “See you at 7”` or `Tapback: Removed a like tapback from a message`. The quoted text appears when Linq can return the original message. An accepted tapback starts or steers a turn like any other message, following `turnPolicy`.
|
|
70
|
+
|
|
71
|
+
`onTapback` runs instead of `onMessage` for tapbacks, so repeat any sender checks from `onMessage` there. The agent's own tapbacks never reach it. Tapbacks arrive as `reaction.added` and `reaction.removed` webhook events, which `eve add channel/linq` subscribes to.
|
|
64
72
|
|
|
65
73
|
To let the agent send tapbacks, export the channel's tapback tool from a file in `agent/tools/`. The file name becomes the tool name:
|
|
66
74
|
|
|
@@ -70,11 +78,13 @@ import linq from "../channels/linq";
|
|
|
70
78
|
export default linq.tapbackTool();
|
|
71
79
|
```
|
|
72
80
|
|
|
73
|
-
The model calls it with a standard tapback, such as `{ "tapback": "love" }`, or any single emoji, such as `{ "tapback": "🎉" }
|
|
81
|
+
The model calls it with a standard tapback, such as `{ "tapback": "love" }`, or any single emoji, such as `{ "tapback": "🎉" }`. eve reacts to the latest message someone sent in the conversation. A standard tapback's own emoji, such as `👍`, sends that tapback.
|
|
82
|
+
|
|
83
|
+
The model can send a tapback alongside a reply; to let a tapback be the whole answer, also add [`no_reply`](../concepts/built-in-tools#no_reply). Subagents don't receive the tool. In a session from another channel, such as web chat, or before anyone has sent a message, the call returns an error to the model.
|
|
74
84
|
|
|
75
85
|
### Answer approvals with a tapback
|
|
76
86
|
|
|
77
|
-
Return `answer` from `onTapback` to answer the
|
|
87
|
+
Return `answer` from `onTapback` to answer the approval or question in the message the tapback is on. A [tool approval](/docs/human-in-the-loop#approvals) offers the options `approve` and `deny`, so a like or dislike on the approval prompt can approve or deny it:
|
|
78
88
|
|
|
79
89
|
```ts title="agent/channels/linq.ts"
|
|
80
90
|
import { connectLinqCredentials } from "@vercel/connect/eve";
|
|
@@ -92,11 +102,13 @@ export default linqChannel({
|
|
|
92
102
|
});
|
|
93
103
|
```
|
|
94
104
|
|
|
95
|
-
`answer`
|
|
105
|
+
`answer` answers only the request posted in that message, and only while that request is still open and offers that option. A tapback on any other message, or on an answered prompt, reaches the agent as an ordinary tapback, such as `Tapback: Liked “Got it”`. The approval's response policy still decides whether the sender may answer. For a [question](/docs/human-in-the-loop#questions), return one of its option ids.
|
|
106
|
+
|
|
107
|
+
Return `message` to replace the text the agent receives for a tapback. Don't set `message` to an option's id, label, or number, because eve reads that text like a typed reply. A typed reply answers the first waiting approval, no matter which message the tapback is on.
|
|
96
108
|
|
|
97
109
|
## Other hosts
|
|
98
110
|
|
|
99
|
-
|
|
111
|
+
On a host without Vercel Connect, choose **Use portable credentials** during `eve add channel/linq`. eve writes `LINQ_API_KEY` and `LINQ_WEBHOOK_SECRET` to `.env.local`.
|
|
100
112
|
|
|
101
113
|
After deploying the agent:
|
|
102
114
|
|
|
@@ -116,7 +128,7 @@ export default linqChannel({
|
|
|
116
128
|
});
|
|
117
129
|
```
|
|
118
130
|
|
|
119
|
-
|
|
131
|
+
A supplied `webhookVerifier` takes precedence over `signingSecret`.
|
|
120
132
|
|
|
121
133
|
## What to read next
|
|
122
134
|
|