Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

fix(dify-agent): enforce short-lived Agent Stub authorization (#40884)

盐粒 Yanlibec389068983
diff --git a/dify-agent-runtime/cmd/dify-agent-cli/dumphelp_test.go b/dify-agent-runtime/cmd/dify-agent-cli/dumphelp_test.go
index a8a0c328f8d..f176b8337c7 100644
--- a/dify-agent-runtime/cmd/dify-agent-cli/dumphelp_test.go
+++ b/dify-agent-runtime/cmd/dify-agent-cli/dumphelp_test.go
@@ -59,6 +59,7 @@ func TestDumpCLIHelpCoversPromptCommands(t *testing.T) {
"config skills delete",
"file upload",
"file download",
+ "file public-url",
}
for _, key := range wantKeys {
if _, ok := table[key]; !ok {
diff --git a/dify-agent-runtime/cmd/dify-agent-cli/main.go b/dify-agent-runtime/cmd/dify-agent-cli/main.go
index 2111d6cd4f1..08bf33f3589 100644
--- a/dify-agent-runtime/cmd/dify-agent-cli/main.go
+++ b/dify-agent-runtime/cmd/dify-agent-cli/main.go
@@ -118,6 +118,14 @@ func newFileCommand() *cobra.Command {
false,
"Skip creating a public download link after upload.",
)
+ publicURL := &cobra.Command{
+ Use: "public-url REFERENCE",
+ Short: "Create a browser-visible download URL for an existing ToolFile reference.",
+ Args: cobra.ExactArgs(1),
+ RunE: withEnv(func(env *agentcli.Environment, args []string, _ *cobra.Command) error {
+ return agentcli.RunFilePublicURL(env, args[0])
+ }),
+ }
var downloadTo string
download := &cobra.Command{
@@ -130,7 +138,7 @@ func newFileCommand() *cobra.Command {
}
download.Flags().StringVar(&downloadTo, "to", "", "Local directory for the downloaded file.")
- cmd.AddCommand(upload, download)
+ cmd.AddCommand(upload, download, publicURL)
return cmd
}
diff --git a/dify-agent-runtime/cmd/dify-agent-cli/main_test.go b/dify-agent-runtime/cmd/dify-agent-cli/main_test.go
index 8e024122c6a..11326c9a8c5 100644
--- a/dify-agent-runtime/cmd/dify-agent-cli/main_test.go
+++ b/dify-agent-runtime/cmd/dify-agent-cli/main_test.go
@@ -65,6 +65,11 @@ func TestCommandHelp(t *testing.T) {
args: []string{"file", "download", "--help"},
want: []string{"dify-agent file download", "Download one workflow file", "--to"},
},
+ {
+ name: "file public-url",
+ args: []string{"file", "public-url", "--help"},
+ want: []string{"dify-agent file public-url", "Create a browser-visible download URL"},
+ },
{
name: "drive",
args: []string{"drive", "--help"},
diff --git a/dify-agent-runtime/internal/agentcli/client.go b/dify-agent-runtime/internal/agentcli/client.go
index 07c80515954..8e84991ab72 100644
--- a/dify-agent-runtime/internal/agentcli/client.go
+++ b/dify-agent-runtime/internal/agentcli/client.go
@@ -7,6 +7,7 @@ type StubClient interface {
// HTTP control-plane
Connect(ctx context.Context, argv []string, metadataJSON string) (*ConnectResponse, error)
CreateFileUploadURL(ctx context.Context, filename, mimetype string) (string, error)
+ CreateToolFileUploadURL(ctx context.Context, filename, mimetype string) (string, error)
CreateFileDownloadURL(ctx context.Context, transferMethod string, reference, url *string, forFrontend bool) (*FileDownloadResponse, error)
// Drive operations (HTTP-only control-plane)
diff --git a/dify-agent-runtime/internal/agentcli/client_http.go b/dify-agent-runtime/internal/agentcli/client_http.go
index fa01c818711..14abb3f368b 100644
--- a/dify-agent-runtime/internal/agentcli/client_http.go
+++ b/dify-agent-runtime/internal/agentcli/client_http.go
@@ -36,8 +36,8 @@ func (c *httpStubClient) Connect(_ context.Context, argv []string, metadataJSON
if err != nil {
return nil, err
}
- if err := checkHTTPError(body, statusCode, "connect"); err != nil {
- return nil, err
+ if err := checkAgentStubHTTPError(body, statusCode); err != nil {
+ return nil, fmt.Errorf("agent stub connect failed: %w", err)
}
var resp ConnectResponse
@@ -72,6 +72,31 @@ func (c *httpStubClient) CreateFileUploadURL(_ context.Context, filename, mimety
return resp.UploadURL, nil
}
+func (c *httpStubClient) CreateToolFileUploadURL(_ context.Context, filename, mimetype string) (string, error) {
+ payload := map[string]string{
+ "filename": filename,
+ "mimetype": mimetype,
+ }
+ body, statusCode, err := c.http.postJSON("/files/upload-request?expose_expiration=true", payload)
+ if err != nil {
+ return "", err
+ }
+ if err := checkAgentStubHTTPError(body, statusCode); err != nil {
+ return "", fmt.Errorf("agent stub file upload request failed: %w", err)
+ }
+
+ var resp struct {
+ UploadURL string `json:"upload_url"`
+ }
+ if err := json.Unmarshal(body, &resp); err != nil {
+ return "", fmt.Errorf("parse upload response: %w", err)
+ }
+ if resp.UploadURL == "" {
+ return "", fmt.Errorf("signed file upload response is missing upload_url")
+ }
+ return resp.UploadURL, nil
+}
+
func (c *httpStubClient) CreateFileDownloadURL(_ context.Context, transferMethod string, reference, url *string, forFrontend bool) (*FileDownloadResponse, error) {
fileMapping := map[string]any{
"transfer_method": transferMethod,
@@ -91,8 +116,8 @@ func (c *httpStubClient) CreateFileDownloadURL(_ context.Context, transferMethod
if err != nil {
return nil, err
}
- if err := checkHTTPError(body, statusCode, "file download request"); err != nil {
- return nil, err
+ if err := checkAgentStubHTTPError(body, statusCode); err != nil {
+ return nil, fmt.Errorf("agent stub file download request failed: %w", err)
}
var resp FileDownloadResponse
@@ -146,8 +171,8 @@ func (c *httpStubClient) GetConfigManifest(_ context.Context) ([]byte, error) {
if err != nil {
return nil, err
}
- if err := checkHTTPError(body, statusCode, "config manifest"); err != nil {
- return nil, err
+ if err := checkAgentStubHTTPError(body, statusCode); err != nil {
+ return nil, fmt.Errorf("agent stub config manifest failed: %w", err)
}
return body, nil
}
@@ -167,8 +192,8 @@ func (c *httpStubClient) CreateConfigDownloadURL(
if err != nil {
return nil, err
}
- if err := checkHTTPError(body, statusCode, "config download request"); err != nil {
- return nil, err
+ if err := checkAgentStubHTTPError(body, statusCode); err != nil {
+ return nil, fmt.Errorf("agent stub config download request failed: %w", err)
}
var resp FileDownloadResponse
@@ -186,8 +211,8 @@ func (c *httpStubClient) PushConfig(_ context.Context, payload any) ([]byte, err
if err != nil {
return nil, err
}
- if err := checkHTTPError(body, statusCode, "config push"); err != nil {
- return nil, err
+ if err := checkAgentStubHTTPError(body, statusCode); err != nil {
+ return nil, fmt.Errorf("agent stub config push failed: %w", err)
}
return body, nil
}
@@ -198,8 +223,8 @@ func (c *httpStubClient) PatchConfigEnv(_ context.Context, envText string) ([]by
if err != nil {
return nil, err
}
- if err := checkHTTPError(body, statusCode, "config env update"); err != nil {
- return nil, err
+ if err := checkAgentStubHTTPError(body, statusCode); err != nil {
+ return nil, fmt.Errorf("agent stub config env update failed: %w", err)
}
return body, nil
}
@@ -210,8 +235,8 @@ func (c *httpStubClient) PutConfigNote(_ context.Context, note string) ([]byte,
if err != nil {
return nil, err
}
- if err := checkHTTPError(body, statusCode, "config note update"); err != nil {
- return nil, err
+ if err := checkAgentStubHTTPError(body, statusCode); err != nil {
+ return nil, fmt.Errorf("agent stub config note update failed: %w", err)
}
return body, nil
}
diff --git a/dify-agent-runtime/internal/agentcli/config.go b/dify-agent-runtime/internal/agentcli/config.go
index d627625c542..69c038a8e2f 100644
--- a/dify-agent-runtime/internal/agentcli/config.go
+++ b/dify-agent-runtime/internal/agentcli/config.go
@@ -76,7 +76,7 @@ func RunConfigSkillsPull(env *Environment, names []string, localDir string, json
for _, name := range names {
download, err := client.CreateConfigDownloadURL(ctx, "skill", name)
if err != nil {
- return err
+ return fmt.Errorf("request config skill %q download URL: %w", name, err)
}
archiveBytes, err := client.DownloadFromURL(download.DownloadURL)
if err != nil {
@@ -174,7 +174,7 @@ func RunConfigFilesPull(env *Environment, names []string, localDir string, jsonO
for _, name := range names {
download, err := client.CreateConfigDownloadURL(ctx, "file", name)
if err != nil {
- return err
+ return fmt.Errorf("request config file %q download URL: %w", name, err)
}
payload, err := client.DownloadFromURL(download.DownloadURL)
if err != nil {
@@ -243,14 +243,14 @@ func RunConfigSkillsPush(env *Environment, paths []string) error {
defer func() { _ = os.Remove(archivePath) }()
name := filepath.Base(absPath)
- commitItem, err := uploadAndPrepareCommitItem(client, archivePath, name)
+ fileRef, err := uploadAndPrepareConfigItem(client, archivePath)
if err != nil {
- return err
+ return fmt.Errorf("upload config skill %q: %w", name, err)
}
skills = append(skills, skillPushItem{
Name: name,
- FileRef: &DriveFileRef{Kind: commitItem.FileRef.Kind, ID: commitItem.FileRef.ID},
+ FileRef: fileRef,
})
}
@@ -261,7 +261,7 @@ func RunConfigSkillsPush(env *Environment, paths []string) error {
body, err := client.PushConfig(context.Background(), payload)
if err != nil {
- return err
+ return fmt.Errorf("push config skills: %w", err)
}
fmt.Println(string(body))
return nil
@@ -296,14 +296,14 @@ func RunConfigFilesPush(env *Environment, paths []string) error {
}
name := filepath.Base(absPath)
- commitItem, err := uploadAndPrepareCommitItem(client, absPath, name)
+ fileRef, err := uploadAndPrepareConfigItem(client, absPath)
if err != nil {
- return err
+ return fmt.Errorf("upload config file %q: %w", name, err)
}
files = append(files, filePushItem{
Name: name,
- FileRef: &DriveFileRef{Kind: commitItem.FileRef.Kind, ID: commitItem.FileRef.ID},
+ FileRef: fileRef,
})
}
@@ -314,12 +314,35 @@ func RunConfigFilesPush(env *Environment, paths []string) error {
body, err := client.PushConfig(context.Background(), payload)
if err != nil {
- return err
+ return fmt.Errorf("push config files: %w", err)
}
fmt.Println(string(body))
return nil
}
+func uploadAndPrepareConfigItem(client StubClient, filePath string) (*DriveFileRef, error) {
+ filename := filepath.Base(filePath)
+ mimetype := guessMIMEType(filename)
+ uploadURL, err := client.CreateToolFileUploadURL(context.Background(), filename, mimetype)
+ if err != nil {
+ return nil, fmt.Errorf("request upload URL: %w", err)
+ }
+ uploadBody, err := client.UploadFileToURL(uploadURL, filePath, filename, mimetype)
+ if err != nil {
+ return nil, fmt.Errorf("upload data: %w", err)
+ }
+
+ var uploadResult map[string]any
+ if err := json.Unmarshal(uploadBody, &uploadResult); err != nil {
+ return nil, fmt.Errorf("parse upload result: %w", err)
+ }
+ toolFileID, _ := uploadResult["id"].(string)
+ if toolFileID == "" {
+ return nil, fmt.Errorf("upload response is missing id")
+ }
+ return &DriveFileRef{Kind: "tool_file", ID: toolFileID}, nil
+}
+
// RunConfigSkillsDelete executes the `config skills delete` command.
func RunConfigSkillsDelete(env *Environment, names []string) error {
if len(names) == 0 {
diff --git a/dify-agent-runtime/internal/agentcli/config_test.go b/dify-agent-runtime/internal/agentcli/config_test.go
index 8f67d5c0863..833932ff545 100644
--- a/dify-agent-runtime/internal/agentcli/config_test.go
+++ b/dify-agent-runtime/internal/agentcli/config_test.go
@@ -4,6 +4,7 @@ import (
"archive/zip"
"bytes"
"encoding/json"
+ "io"
"net/http"
"net/http/httptest"
"os"
@@ -111,52 +112,344 @@ func TestConfigPullRequestsURLThenDownloadsFromDataPlane(t *testing.T) {
}
}
-func TestConfigPullReportsControlAndDataPlaneFailures(t *testing.T) {
+func TestConfigPullMultiItemFailuresIdentifyItemAndStage(t *testing.T) {
+ skillArchive := zipFixture(t, map[string]string{"SKILL.md": "# Alpha\n"})
tests := []struct {
- name string
- controlStatus int
- dataStatus int
- want string
+ name string
+ kind string
+ names []string
+ payload []byte
+ failureStage string
+ wantStage string
}{
- {name: "control", controlStatus: http.StatusNotFound, dataStatus: http.StatusOK, want: "config download request failed"},
- {name: "data plane", controlStatus: http.StatusOK, dataStatus: http.StatusBadGateway, want: "download config file"},
+ {
+ name: "file control-plane URL acquisition",
+ kind: "file",
+ names: []string{"first.txt", "second.txt"},
+ payload: []byte("first file"),
+ failureStage: "control",
+ wantStage: `request config file "second.txt" download URL`,
+ },
+ {
+ name: "file signed-URL download",
+ kind: "file",
+ names: []string{"first.txt", "second.txt"},
+ payload: []byte("first file"),
+ failureStage: "data",
+ wantStage: `download config file "second.txt"`,
+ },
+ {
+ name: "skill control-plane URL acquisition",
+ kind: "skill",
+ names: []string{"alpha", "beta"},
+ payload: skillArchive,
+ failureStage: "control",
+ wantStage: `request config skill "beta" download URL`,
+ },
+ {
+ name: "skill signed-URL download",
+ kind: "skill",
+ names: []string{"alpha", "beta"},
+ payload: skillArchive,
+ failureStage: "data",
+ wantStage: `download config skill "beta"`,
+ },
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
+ controlCalls := 0
+ dataPlaneCalls := 0
var server *httptest.Server
server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case "/agent-stub/files/download-request":
- if test.controlStatus != http.StatusOK {
- w.WriteHeader(test.controlStatus)
- _, _ = w.Write([]byte(`{"detail":"missing"}`))
+ controlCalls++
+ var request struct {
+ Config struct {
+ Kind string `json:"kind"`
+ Name string `json:"name"`
+ } `json:"config"`
+ }
+ if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+ t.Errorf("decode download request: %v", err)
+ http.Error(w, "bad request", http.StatusBadRequest)
+ return
+ }
+ if controlCalls > len(test.names) {
+ t.Errorf("unexpected control-plane call %d", controlCalls)
+ http.Error(w, "unexpected request", http.StatusInternalServerError)
+ return
+ }
+ wantName := test.names[controlCalls-1]
+ if request.Config.Kind != test.kind || request.Config.Name != wantName {
+ t.Errorf("config request = (%q, %q), want (%q, %q)", request.Config.Kind, request.Config.Name, test.kind, wantName)
+ }
+ if test.failureStage == "control" && controlCalls == 2 {
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusUnauthorized)
+ _, _ = w.Write([]byte(`{"detail":{"code":"agent_stub_authorization_expired","message":"expired"}}`))
return
}
_ = json.NewEncoder(w).Encode(map[string]any{
- "filename": "guide.txt", "size": 5, "download_url": server.URL + "/files/config-asset",
+ "filename": wantName,
+ "size": len(test.payload),
+ "download_url": server.URL + "/files/config-asset",
})
case "/files/config-asset":
- w.WriteHeader(test.dataStatus)
+ dataPlaneCalls++
+ if test.failureStage == "data" && dataPlaneCalls == 2 {
+ http.Error(w, "data plane unavailable", http.StatusBadGateway)
+ return
+ }
+ _, _ = w.Write(test.payload)
+ default:
+ http.NotFound(w, r)
+ }
+ }))
+ defer server.Close()
+
+ targetDir := t.TempDir()
+ env := &Environment{URL: server.URL + "/agent-stub", AuthJWE: "token"}
+ var err error
+ if test.kind == "file" {
+ err = RunConfigFilesPull(env, test.names, targetDir, true)
+ } else {
+ err = RunConfigSkillsPull(env, test.names, targetDir, true)
+ }
+ if err == nil {
+ t.Fatal("config pull succeeded, want second-item failure")
+ }
+ if !strings.Contains(err.Error(), test.wantStage) {
+ t.Errorf("error = %q, want stage %q", err, test.wantStage)
+ }
+ if controlCalls != 2 {
+ t.Errorf("control-plane calls = %d, want 2", controlCalls)
+ }
+ wantDataPlaneCalls := 2
+ if test.failureStage == "control" {
+ wantDataPlaneCalls = 1
+ for _, want := range []string{
+ "expired after 5 minutes",
+ "will not refresh automatically",
+ "start a new shell tool call",
+ "retry the command",
+ } {
+ if !strings.Contains(err.Error(), want) {
+ t.Errorf("error = %q, want expiration guidance %q", err, want)
+ }
+ }
+ }
+ if dataPlaneCalls != wantDataPlaneCalls {
+ t.Errorf("data-plane calls = %d, want %d", dataPlaneCalls, wantDataPlaneCalls)
+ }
+
+ if test.kind == "file" {
+ data, readErr := os.ReadFile(filepath.Join(targetDir, test.names[0]))
+ if readErr != nil || !bytes.Equal(data, test.payload) {
+ t.Errorf("first file was not completed: data=%q err=%v", data, readErr)
+ }
+ } else {
+ data, readErr := os.ReadFile(filepath.Join(targetDir, test.names[0], "SKILL.md"))
+ if readErr != nil || string(data) != "# Alpha\n" {
+ t.Errorf("first skill was not completed: data=%q err=%v", data, readErr)
+ }
+ }
+ })
+ }
+}
+
+func TestConfigPushMultiItemUploadFailuresIdentifyItemAndStage(t *testing.T) {
+ tests := []struct {
+ name string
+ failureStage string
+ makeSources func(*testing.T) []string
+ run func(*Environment, []string) error
+ wantItem string
+ }{
+ {
+ name: "file control-plane URL acquisition",
+ failureStage: "request upload URL",
+ makeSources: makeConfigFileSources,
+ run: RunConfigFilesPush,
+ wantItem: `config file "second.txt"`,
+ },
+ {
+ name: "file signed URL data transfer",
+ failureStage: "upload data",
+ makeSources: makeConfigFileSources,
+ run: RunConfigFilesPush,
+ wantItem: `config file "second.txt"`,
+ },
+ {
+ name: "skill control-plane URL acquisition",
+ failureStage: "request upload URL",
+ makeSources: makeConfigSkillSources,
+ run: RunConfigSkillsPush,
+ wantItem: `config skill "beta"`,
+ },
+ {
+ name: "skill signed URL data transfer",
+ failureStage: "upload data",
+ makeSources: makeConfigSkillSources,
+ run: RunConfigSkillsPush,
+ wantItem: `config skill "beta"`,
+ },
+ }
+
+ for _, test := range tests {
+ t.Run(test.name, func(t *testing.T) {
+ uploadRequestCalls := 0
+ dataPlaneCalls := 0
+ var server *httptest.Server
+ server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/agent-stub/files/upload-request":
+ uploadRequestCalls++
+ if test.failureStage == "request upload URL" && uploadRequestCalls == 2 {
+ http.Error(w, "control plane unavailable", http.StatusServiceUnavailable)
+ return
+ }
+ _ = json.NewEncoder(w).Encode(map[string]string{"upload_url": server.URL + "/upload"})
+ case "/upload":
+ _, _ = io.Copy(io.Discard, r.Body)
+ dataPlaneCalls++
+ if test.failureStage == "upload data" && dataPlaneCalls == 2 {
+ http.Error(w, "data plane unavailable", http.StatusBadGateway)
+ return
+ }
+ _, _ = w.Write([]byte(`{"id":"tool-file-1"}`))
+ case "/agent-stub/config/push":
+ t.Error("final config push must not run after an item upload failure")
+ default:
+ http.NotFound(w, r)
+ }
+ }))
+ defer server.Close()
+
+ err := test.run(
+ &Environment{URL: server.URL + "/agent-stub", AuthJWE: "token"},
+ test.makeSources(t),
+ )
+ if err == nil {
+ t.Fatal("config push succeeded, want second-item upload failure")
+ }
+ if !strings.Contains(err.Error(), test.wantItem) {
+ t.Errorf("error = %q, want current item %q", err, test.wantItem)
+ }
+ if !strings.Contains(err.Error(), test.failureStage) {
+ t.Errorf("error = %q, want stage %q", err, test.failureStage)
+ }
+ if uploadRequestCalls != 2 {
+ t.Errorf("upload request calls = %d, want 2", uploadRequestCalls)
+ }
+ wantDataPlaneCalls := 2
+ if test.failureStage == "request upload URL" {
+ wantDataPlaneCalls = 1
+ }
+ if dataPlaneCalls != wantDataPlaneCalls {
+ t.Errorf("data-plane calls = %d, want %d", dataPlaneCalls, wantDataPlaneCalls)
+ }
+ })
+ }
+}
+
+func TestConfigPushFinalFailureIdentifiesOperationAndExplainsExpiry(t *testing.T) {
+ tests := []struct {
+ name string
+ makeSource func(*testing.T) string
+ run func(*Environment, string) error
+ want string
+ }{
+ {
+ name: "file",
+ makeSource: func(t *testing.T) string {
+ path := filepath.Join(t.TempDir(), "guide.txt")
+ if err := os.WriteFile(path, []byte("guide"), 0o600); err != nil {
+ t.Fatalf("write config file: %v", err)
+ }
+ return path
+ },
+ run: func(env *Environment, path string) error { return RunConfigFilesPush(env, []string{path}) },
+ want: "push config files",
+ },
+ {
+ name: "skill",
+ makeSource: func(t *testing.T) string {
+ dir := filepath.Join(t.TempDir(), "alpha")
+ if err := os.MkdirAll(dir, 0o755); err != nil {
+ t.Fatalf("create config skill: %v", err)
+ }
+ if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte("# Alpha\n"), 0o600); err != nil {
+ t.Fatalf("write config skill: %v", err)
+ }
+ return dir
+ },
+ run: func(env *Environment, path string) error { return RunConfigSkillsPush(env, []string{path}) },
+ want: "push config skills",
+ },
+ }
+
+ for _, test := range tests {
+ t.Run(test.name, func(t *testing.T) {
+ var server *httptest.Server
+ server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/agent-stub/files/upload-request":
+ _ = json.NewEncoder(w).Encode(map[string]string{"upload_url": server.URL + "/upload"})
+ case "/upload":
+ _, _ = w.Write([]byte(`{"id":"tool-file-1"}`))
+ case "/agent-stub/config/push":
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusUnauthorized)
+ _, _ = w.Write([]byte(`{"detail":{"code":"agent_stub_authorization_expired","message":"expired"}}`))
default:
http.NotFound(w, r)
}
}))
defer server.Close()
- err := RunConfigFilesPull(
+ err := test.run(
&Environment{URL: server.URL + "/agent-stub", AuthJWE: "token"},
- []string{"guide.txt"},
- t.TempDir(),
- true,
+ test.makeSource(t),
)
if err == nil || !strings.Contains(err.Error(), test.want) {
- t.Fatalf("error = %v, want substring %q", err, test.want)
+ t.Fatalf("error = %v, want operation %q", err, test.want)
+ }
+ if !strings.Contains(err.Error(), "start a new shell tool call") {
+ t.Fatalf("error = %v, want expiry recovery guidance", err)
}
})
}
}
+func makeConfigFileSources(t *testing.T) []string {
+ t.Helper()
+ dir := t.TempDir()
+ paths := []string{filepath.Join(dir, "first.txt"), filepath.Join(dir, "second.txt")}
+ for _, path := range paths {
+ if err := os.WriteFile(path, []byte(filepath.Base(path)), 0o600); err != nil {
+ t.Fatalf("write config file: %v", err)
+ }
+ }
+ return paths
+}
+
+func makeConfigSkillSources(t *testing.T) []string {
+ t.Helper()
+ dir := t.TempDir()
+ paths := []string{filepath.Join(dir, "alpha"), filepath.Join(dir, "beta")}
+ for _, path := range paths {
+ if err := os.MkdirAll(path, 0o755); err != nil {
+ t.Fatalf("create config skill: %v", err)
+ }
+ if err := os.WriteFile(filepath.Join(path, "SKILL.md"), []byte("# "+filepath.Base(path)+"\n"), 0o600); err != nil {
+ t.Fatalf("write config skill: %v", err)
+ }
+ }
+ return paths
+}
+
func zipFixture(t *testing.T, files map[string]string) []byte {
t.Helper()
var buffer bytes.Buffer
diff --git a/dify-agent-runtime/internal/agentcli/connect_test.go b/dify-agent-runtime/internal/agentcli/connect_test.go
new file mode 100644
index 00000000000..9d83ea5d4fa
--- /dev/null
+++ b/dify-agent-runtime/internal/agentcli/connect_test.go
@@ -0,0 +1,53 @@
+package agentcli
+
+import (
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+)
+
+func TestRunConnectExplainsExpiredAuthorization(t *testing.T) {
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/agent-stub/connections" {
+ http.NotFound(w, r)
+ return
+ }
+ var payload struct {
+ Argv []string `json:"argv"`
+ }
+ if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
+ t.Errorf("decode connect request: %v", err)
+ http.Error(w, "bad request", http.StatusBadRequest)
+ return
+ }
+ if got, want := strings.Join(payload.Argv, " "), "echo hello"; got != want {
+ t.Errorf("argv = %q, want %q", got, want)
+ }
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusUnauthorized)
+ _, _ = w.Write([]byte(`{"detail":{"code":"agent_stub_authorization_expired","message":"Agent Stub authorization expired after 5 minutes; start a new shell tool call and retry the command."}}`))
+ }))
+ defer server.Close()
+
+ err := RunConnect(
+ &Environment{URL: server.URL + "/agent-stub", AuthJWE: "token"},
+ []string{"echo", "hello"},
+ false,
+ )
+ if err == nil {
+ t.Fatal("RunConnect succeeded, want expired authorization failure")
+ }
+ for _, want := range []string{
+ "agent stub connect failed",
+ "expired after 5 minutes",
+ "will not refresh automatically",
+ "start a new shell tool call",
+ "retry the command",
+ } {
+ if !strings.Contains(err.Error(), want) {
+ t.Errorf("error = %q, want substring %q", err, want)
+ }
+ }
+}
diff --git a/dify-agent-runtime/internal/agentcli/file.go b/dify-agent-runtime/internal/agentcli/file.go
index b1f5179bb60..cbc1c9c3096 100644
--- a/dify-agent-runtime/internal/agentcli/file.go
+++ b/dify-agent-runtime/internal/agentcli/file.go
@@ -39,8 +39,12 @@ func RunFileUpload(env *Environment, path string, noDownloadLink bool) error {
}
type fileUploadClient interface {
- CreateFileUploadURL(ctx context.Context, filename, mimetype string) (string, error)
+ filePublicURLClient
+ CreateToolFileUploadURL(ctx context.Context, filename, mimetype string) (string, error)
UploadFileToURL(uploadURL, filePath, filename, mimetype string) ([]byte, error)
+}
+
+type filePublicURLClient interface {
CreateFileDownloadURL(
ctx context.Context,
transferMethod string,
@@ -64,15 +68,15 @@ func runFileUpload(client fileUploadClient, path string, noDownloadLink bool, ou
ctx := context.Background()
// Step 1: Request a signed upload URL
- uploadURL, err := client.CreateFileUploadURL(ctx, filename, mimetype)
+ uploadURL, err := client.CreateToolFileUploadURL(ctx, filename, mimetype)
if err != nil {
- return err
+ return fmt.Errorf("request file upload URL: %w", err)
}
// Step 2: Upload the file to the signed URL (data-plane)
uploadBody, err := client.UploadFileToURL(uploadURL, absPath, filename, mimetype)
if err != nil {
- return err
+ return fmt.Errorf("upload file data: %w", err)
}
var uploadResult map[string]any
@@ -84,7 +88,7 @@ func runFileUpload(client fileUploadClient, path string, noDownloadLink bool, ou
if reference == "" {
return fmt.Errorf("signed file upload response is missing reference")
}
- if noDownloadLink && !isCanonicalDifyFileReference(reference) {
+ if !isCanonicalDifyFileReference(reference) {
return fmt.Errorf("signed file upload response has invalid reference")
}
@@ -98,13 +102,63 @@ func runFileUpload(client fileUploadClient, path string, noDownloadLink bool, ou
ref := reference
dlResp, err := client.CreateFileDownloadURL(ctx, "tool_file", &ref, nil, true)
if err != nil {
- return err
+ writeFileUploadResponse(output, result)
+ return fmt.Errorf(
+ "request public download URL: %w; retry without uploading again: dify-agent file public-url %s",
+ err,
+ shellQuoteArgument(reference),
+ )
+ }
+ if dlResp.DownloadURL == "" {
+ writeFileUploadResponse(output, result)
+ return fmt.Errorf(
+ "public file download response is missing download_url; retry without uploading again: dify-agent file public-url %s",
+ shellQuoteArgument(reference),
+ )
}
result.PublicDownloadURL = dlResp.DownloadURL
}
+ writeFileUploadResponse(output, result)
+ return nil
+}
+
+// RunFilePublicURL requests a browser-visible URL for an existing ToolFile reference.
+func RunFilePublicURL(env *Environment, reference string) error {
+ client, err := NewStubClient(env)
+ if err != nil {
+ return err
+ }
+ defer func() { _ = client.Close() }()
+
+ return runFilePublicURL(client, reference, os.Stdout)
+}
+
+func runFilePublicURL(client filePublicURLClient, reference string, output io.Writer) error {
+ if reference == "" {
+ return fmt.Errorf("file reference must not be empty")
+ }
+ download, err := client.CreateFileDownloadURL(context.Background(), "tool_file", &reference, nil, true)
+ if err != nil {
+ return fmt.Errorf("request public download URL: %w", err)
+ }
+ if download.DownloadURL == "" {
+ return fmt.Errorf("public file download response is missing download_url")
+ }
+ writeFileUploadResponse(output, FileUploadResponse{
+ TransferMethod: "tool_file",
+ Reference: reference,
+ PublicDownloadURL: download.DownloadURL,
+ })
+ return nil
+}
+
+func writeFileUploadResponse(output io.Writer, result FileUploadResponse) {
out, _ := json.Marshal(result)
_, _ = fmt.Fprintln(output, string(out))
- return nil
+}
+
+func shellQuoteArgument(value string) string {
+ return "'" + strings.ReplaceAll(value, "'", `'"'"'`) + "'"
}
func isCanonicalDifyFileReference(reference string) bool {
@@ -144,7 +198,7 @@ func RunFileDownload(env *Environment, transferMethod string, referenceOrURL str
dlResp, err := client.CreateFileDownloadURL(ctx, transferMethod, reference, url, false)
if err != nil {
- return err
+ return fmt.Errorf("request file download URL: %w", err)
}
if dlResp.DownloadURL == "" {
return fmt.Errorf("signed file download response is missing download_url")
@@ -156,7 +210,7 @@ func RunFileDownload(env *Environment, transferMethod string, referenceOrURL str
// Download the file (data-plane)
data, err := client.DownloadFromURL(dlResp.DownloadURL)
if err != nil {
- return err
+ return fmt.Errorf("download file data: %w", err)
}
// Determine target directory
diff --git a/dify-agent-runtime/internal/agentcli/file_test.go b/dify-agent-runtime/internal/agentcli/file_test.go
index a610457e6c2..bde80828a9f 100644
--- a/dify-agent-runtime/internal/agentcli/file_test.go
+++ b/dify-agent-runtime/internal/agentcli/file_test.go
@@ -15,6 +15,7 @@ import (
type fakeFileUploadClient struct {
forFrontend bool
downloadRequestCall int
+ downloadMethod string
uploadResponse []byte
calls []string
filename string
@@ -22,9 +23,11 @@ type fakeFileUploadClient struct {
uploadURL string
uploadedBytes []byte
downloadReference string
+ downloadErr error
+ downloadURL *string
}
-func (f *fakeFileUploadClient) CreateFileUploadURL(_ context.Context, filename, mimetype string) (string, error) {
+func (f *fakeFileUploadClient) CreateToolFileUploadURL(_ context.Context, filename, mimetype string) (string, error) {
f.calls = append(f.calls, "upload-request")
f.filename = filename
f.mimetype = mimetype
@@ -45,21 +48,29 @@ func (f *fakeFileUploadClient) UploadFileToURL(uploadURL, filePath, filename, mi
func (f *fakeFileUploadClient) CreateFileDownloadURL(
_ context.Context,
- _ string,
+ transferMethod string,
reference, _ *string,
forFrontend bool,
) (*FileDownloadResponse, error) {
f.calls = append(f.calls, "download-request")
f.forFrontend = forFrontend
+ f.downloadMethod = transferMethod
f.downloadRequestCall++
if reference != nil {
f.downloadReference = *reference
}
+ if f.downloadErr != nil {
+ return nil, f.downloadErr
+ }
+ downloadURL := "/files/tools/report.pdf?sign=2"
+ if f.downloadURL != nil {
+ downloadURL = *f.downloadURL
+ }
return &FileDownloadResponse{
Filename: "report.pdf",
MimeType: "application/pdf",
Size: 123,
- DownloadURL: "/files/tools/report.pdf?sign=2",
+ DownloadURL: downloadURL,
}, nil
}
@@ -125,43 +136,146 @@ func TestRunFileUploadWithoutDownloadLinkReturnsOnlyCanonicalMapping(t *testing.
}
}
-func TestRunFileUploadDefaultAcceptsLegacyNonemptyReference(t *testing.T) {
+func TestRunFileUploadPreservesReferenceWhenPublicURLRequestFails(t *testing.T) {
filePath := filepath.Join(t.TempDir(), "report.pdf")
if err := os.WriteFile(filePath, []byte("report"), 0o600); err != nil {
t.Fatalf("write fixture: %v", err)
}
- client := &fakeFileUploadClient{uploadResponse: []byte(`{"reference":"raw-id"}`)}
+ client := &fakeFileUploadClient{downloadErr: &agentStubHTTPError{
+ statusCode: http.StatusUnauthorized,
+ code: agentStubAuthorizationExpiredCode,
+ message: "expired",
+ }}
var output bytes.Buffer
err := runFileUpload(client, filePath, false, &output)
- if err != nil {
- t.Fatalf("run file upload: %v", err)
+ if err == nil {
+ t.Fatal("run file upload succeeded, want public URL failure")
+ }
+ const reference = "dify-file-ref:eyJyZWNvcmRfaWQiOiJ0b29sLTEifQ=="
+ if got, want := strings.TrimSpace(output.String()), `{"transfer_method":"tool_file","reference":"`+reference+`"}`; got != want {
+ t.Fatalf("partial output = %s, want %s", got, want)
+ }
+ for _, want := range []string{
+ "request public download URL",
+ "expired after 5 minutes",
+ "will not refresh automatically",
+ "start a new shell tool call",
+ "retry the command",
+ } {
+ if !strings.Contains(err.Error(), want) {
+ t.Errorf("error = %q, want substring %q", err, want)
+ }
}
- if client.downloadRequestCall != 1 || client.downloadReference != "raw-id" {
- t.Fatalf("download request = (%d, %q), want legacy reference", client.downloadRequestCall, client.downloadReference)
+ recoveryCommand := "dify-agent file public-url '" + reference + "'"
+ if !strings.HasSuffix(err.Error(), "retry without uploading again: "+recoveryCommand) {
+ t.Fatalf("error = %q, want exact recovery command %q", err, recoveryCommand)
}
- if !strings.Contains(output.String(), `"reference":"raw-id"`) {
- t.Fatalf("output = %q, want legacy reference", output.String())
+ if got, want := strings.Join(client.calls, ","), "upload-request,multipart-upload,download-request"; got != want {
+ t.Fatalf("call order = %s, want %s", got, want)
}
}
-func TestRunFileUploadWithoutDownloadLinkRejectsNonCanonicalReference(t *testing.T) {
+func TestRunFileUploadPreservesReferenceWhenPublicURLResponseIsIncomplete(t *testing.T) {
filePath := filepath.Join(t.TempDir(), "report.pdf")
if err := os.WriteFile(filePath, []byte("report"), 0o600); err != nil {
t.Fatalf("write fixture: %v", err)
}
- client := &fakeFileUploadClient{uploadResponse: []byte(`{"reference":"raw-id"}`)}
+ emptyURL := ""
+ client := &fakeFileUploadClient{downloadURL: &emptyURL}
var output bytes.Buffer
- err := runFileUpload(client, filePath, true, &output)
- if err == nil || !strings.Contains(err.Error(), "invalid reference") {
- t.Fatalf("error = %v, want invalid reference", err)
+ err := runFileUpload(client, filePath, false, &output)
+ if err == nil || !strings.Contains(err.Error(), "missing download_url") {
+ t.Fatalf("error = %v, want incomplete public URL response", err)
}
- if client.downloadRequestCall != 0 {
- t.Fatalf("download request calls = %d, want 0", client.downloadRequestCall)
+ if !strings.Contains(output.String(), `"reference":"dify-file-ref:`) {
+ t.Fatalf("partial output = %q, want uploaded reference", output.String())
}
- if output.Len() != 0 {
- t.Fatalf("output = %q, want empty", output.String())
+ if !strings.Contains(err.Error(), "dify-agent file public-url") {
+ t.Fatalf("error = %q, want recovery command", err)
+ }
+}
+
+func TestRunFilePublicURLUsesExistingReferenceWithoutUploading(t *testing.T) {
+ client := &fakeFileUploadClient{}
+ var output bytes.Buffer
+ const reference = "dify-file-ref:eyJyZWNvcmRfaWQiOiJ0b29sLTEifQ=="
+
+ if err := runFilePublicURL(client, reference, &output); err != nil {
+ t.Fatalf("run file public URL: %v", err)
+ }
+
+ if got, want := strings.Join(client.calls, ","), "download-request"; got != want {
+ t.Fatalf("calls = %s, want %s", got, want)
+ }
+ if !client.forFrontend || client.downloadMethod != "tool_file" || client.downloadReference != reference {
+ t.Fatalf(
+ "download request = (method=%q, forFrontend=%t, reference=%q)",
+ client.downloadMethod,
+ client.forFrontend,
+ client.downloadReference,
+ )
+ }
+ want := `{"transfer_method":"tool_file","reference":"` + reference + `","public_download_url":"/files/tools/report.pdf?sign=2"}`
+ if got := strings.TrimSpace(output.String()); got != want {
+ t.Fatalf("output = %s, want %s", got, want)
+ }
+}
+
+func TestRunFilePublicURLExplainsExpiredAuthorization(t *testing.T) {
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/agent-stub/files/download-request" {
+ http.NotFound(w, r)
+ return
+ }
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusUnauthorized)
+ _, _ = w.Write([]byte(`{"detail":{"code":"agent_stub_authorization_expired","message":"expired"}}`))
+ }))
+ defer server.Close()
+
+ err := RunFilePublicURL(
+ &Environment{URL: server.URL + "/agent-stub", AuthJWE: "token"},
+ "dify-file-ref:eyJyZWNvcmRfaWQiOiJ0b29sLTEifQ==",
+ )
+ if err == nil {
+ t.Fatal("RunFilePublicURL succeeded, want expired authorization failure")
+ }
+ for _, want := range []string{
+ "request public download URL",
+ "expired after 5 minutes",
+ "will not refresh automatically",
+ "start a new shell tool call",
+ "retry the command",
+ } {
+ if !strings.Contains(err.Error(), want) {
+ t.Errorf("error = %q, want substring %q", err, want)
+ }
+ }
+}
+
+func TestRunFileUploadRejectsNonCanonicalReferenceInBothModes(t *testing.T) {
+ filePath := filepath.Join(t.TempDir(), "report.pdf")
+ if err := os.WriteFile(filePath, []byte("report"), 0o600); err != nil {
+ t.Fatalf("write fixture: %v", err)
+ }
+
+ for _, noDownloadLink := range []bool{false, true} {
+ client := &fakeFileUploadClient{uploadResponse: []byte(`{"reference":"raw-id"}`)}
+ var output bytes.Buffer
+ err := runFileUpload(client, filePath, noDownloadLink, &output)
+ if err == nil || !strings.Contains(err.Error(), "invalid reference") {
+ t.Fatalf("noDownloadLink=%t error = %v, want invalid reference", noDownloadLink, err)
+ }
+ if client.downloadRequestCall != 0 || output.Len() != 0 {
+ t.Fatalf(
+ "noDownloadLink=%t download calls = %d, output = %q; want no download or output",
+ noDownloadLink,
+ client.downloadRequestCall,
+ output.String(),
+ )
+ }
}
}
diff --git a/dify-agent-runtime/internal/agentcli/httpclient.go b/dify-agent-runtime/internal/agentcli/httpclient.go
index 0c2c156c16b..93cd0d073e2 100644
--- a/dify-agent-runtime/internal/agentcli/httpclient.go
+++ b/dify-agent-runtime/internal/agentcli/httpclient.go
@@ -25,6 +25,24 @@ type HTTPClient struct {
var errUploadRequestAborted = errors.New("upload request aborted")
+const agentStubAuthorizationExpiredCode = "agent_stub_authorization_expired"
+
+type agentStubHTTPError struct {
+ statusCode int
+ code string
+ message string
+}
+
+func (e *agentStubHTTPError) Error() string {
+ if e.code == agentStubAuthorizationExpiredCode {
+ return fmt.Sprintf(
+ "HTTP %d: Agent Stub authorization expired after 5 minutes; the authorization in this process will not refresh automatically; start a new shell tool call and retry the command",
+ e.statusCode,
+ )
+ }
+ return fmt.Sprintf("HTTP %d: %s", e.statusCode, e.message)
+}
+
// NewHTTPClient creates a new HTTP client for the Agent Stub API.
func NewHTTPClient(env *Environment) *HTTPClient {
return &HTTPClient{
@@ -297,3 +315,37 @@ func checkHTTPError(body []byte, statusCode int, operation string) error {
}
return fmt.Errorf("agent stub %s failed (HTTP %d): %s", operation, statusCode, string(body))
}
+
+// checkAgentStubHTTPError decodes structured errors for Agent-visible
+// connect, file, and config commands. Drive retains its legacy error contract.
+func checkAgentStubHTTPError(body []byte, statusCode int) error {
+ if statusCode < 400 {
+ return nil
+ }
+
+ message := string(body)
+ code := ""
+ var response struct {
+ Detail json.RawMessage `json:"detail"`
+ }
+ if json.Unmarshal(body, &response) == nil && len(response.Detail) > 0 {
+ var detailMessage string
+ if json.Unmarshal(response.Detail, &detailMessage) == nil {
+ message = detailMessage
+ } else {
+ var detail struct {
+ Code string `json:"code"`
+ Message string `json:"message"`
+ }
+ if json.Unmarshal(response.Detail, &detail) == nil {
+ code = detail.Code
+ if detail.Message != "" {
+ message = detail.Message
+ } else {
+ message = string(response.Detail)
+ }
+ }
+ }
+ }
+ return &agentStubHTTPError{statusCode: statusCode, code: code, message: message}
+}
diff --git a/dify-agent-runtime/internal/agentcli/httpclient_test.go b/dify-agent-runtime/internal/agentcli/httpclient_test.go
index 67ac9dbd11e..33d558f5378 100644
--- a/dify-agent-runtime/internal/agentcli/httpclient_test.go
+++ b/dify-agent-runtime/internal/agentcli/httpclient_test.go
@@ -2,6 +2,7 @@ package agentcli
import (
"bytes"
+ "context"
"errors"
"fmt"
"io"
@@ -418,6 +419,88 @@ func TestUploadFileRejectsOversizedResponse(t *testing.T) {
}
}
+func TestCheckAgentStubHTTPErrorParsesSupportedResponseShapes(t *testing.T) {
+ tests := []struct {
+ name string
+ body string
+ wantMessage string
+ }{
+ {
+ name: "string detail",
+ body: `{"detail":"invalid request"}`,
+ wantMessage: "invalid request",
+ },
+ {
+ name: "non JSON body",
+ body: "gateway unavailable",
+ wantMessage: "gateway unavailable",
+ },
+ }
+
+ for _, test := range tests {
+ t.Run(test.name, func(t *testing.T) {
+ err := checkAgentStubHTTPError([]byte(test.body), http.StatusUnauthorized)
+ var httpErr *agentStubHTTPError
+ if !errors.As(err, &httpErr) {
+ t.Fatalf("error = %v, want *agentStubHTTPError", err)
+ }
+ if httpErr.statusCode != http.StatusUnauthorized || httpErr.code != "" {
+ t.Fatalf("parsed error = %#v", httpErr)
+ }
+ if !strings.Contains(err.Error(), test.wantMessage) {
+ t.Fatalf("error = %q, want substring %q", err, test.wantMessage)
+ }
+ })
+ }
+}
+
+func TestAgentStubAuthorizationExpiryErrorExplainsHowToRefresh(t *testing.T) {
+ err := checkAgentStubHTTPError(
+ []byte(`{"detail":{"code":"agent_stub_authorization_expired","message":"expired"}}`),
+ http.StatusUnauthorized,
+ )
+ var httpErr *agentStubHTTPError
+ if !errors.As(err, &httpErr) {
+ t.Fatalf("error = %v, want *agentStubHTTPError", err)
+ }
+ if httpErr.statusCode != http.StatusUnauthorized {
+ t.Fatalf("status = %d, want %d", httpErr.statusCode, http.StatusUnauthorized)
+ }
+ if httpErr.code != agentStubAuthorizationExpiredCode || httpErr.message != "expired" {
+ t.Fatalf("parsed error = %#v", httpErr)
+ }
+
+ for _, want := range []string{
+ "expired after 5 minutes",
+ "will not refresh automatically",
+ "start a new shell tool call",
+ "retry the command",
+ } {
+ if !strings.Contains(err.Error(), want) {
+ t.Errorf("error = %q, want substring %q", err, want)
+ }
+ }
+}
+
+func TestToolFileUploadURLAloneOptsIntoStructuredExpiration(t *testing.T) {
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Query().Get("expose_expiration") != "true" {
+ t.Errorf("expose_expiration = %q, want true", r.URL.Query().Get("expose_expiration"))
+ }
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusUnauthorized)
+ _, _ = w.Write([]byte(`{"detail":{"code":"agent_stub_authorization_expired","message":"expired"}}`))
+ }))
+ defer server.Close()
+
+ client := newHTTPStubClient(&Environment{URL: server.URL, AuthJWE: "token"})
+ _, toolFileErr := client.CreateToolFileUploadURL(context.Background(), "report.pdf", "application/pdf")
+
+ if toolFileErr == nil || !strings.Contains(toolFileErr.Error(), "start a new shell tool call") {
+ t.Fatalf("ToolFile error = %v, want structured expiry guidance", toolFileErr)
+ }
+}
+
func TestUploadFileReturnsNonSuccessStatus(t *testing.T) {
filePath := filepath.Join(t.TempDir(), "payload.txt")
if err := os.WriteFile(filePath, []byte("payload"), 0o600); err != nil {
diff --git a/dify-agent/docs/dify-agent/user-manual/shell-layer/index.md b/dify-agent/docs/dify-agent/user-manual/shell-layer/index.md
index 4066cc5c866..97155355f62 100644
--- a/dify-agent/docs/dify-agent/user-manual/shell-layer/index.md
+++ b/dify-agent/docs/dify-agent/user-manual/shell-layer/index.md
@@ -124,6 +124,22 @@ the same streaming ToolFile upload but skips the download-request step and
prints only `transfer_method` plus the canonical `reference`. The regular
`file upload` command keeps the link-producing behavior shown above.
+If the upload succeeds but creating the public URL fails, the command still
+prints the canonical mapping and exits with an error containing an exact
+`dify-agent file public-url <reference>` retry command. Run that command from a
+new shell tool call to create the public URL without uploading the file again.
+On success, `file public-url` prints the complete JSON mapping containing
+`transfer_method`, `reference`, and `public_download_url`.
+
+The Agent Stub authorization injected into a shell job is valid for five
+minutes. It does not refresh inside an already-running process. If a command
+reports that the authorization expired, start a new shell tool call and retry
+the command (or its reported `file public-url` recovery command).
+
+The injected JWE is masked as `***` in model-facing `shell_run`, `shell_wait`,
+and `shell_input` observations. Raw shellctl output and files referenced by
+`output_path` remain unchanged.
+
## Request graph
A shell-enabled run contains Execution Context, Runtime, and Shell layers:
diff --git a/dify-agent/src/dify_agent/agent_stub/server/control_plane.py b/dify-agent/src/dify_agent/agent_stub/server/control_plane.py
index 05eba042288..badf83dc41c 100644
--- a/dify-agent/src/dify_agent/agent_stub/server/control_plane.py
+++ b/dify-agent/src/dify_agent/agent_stub/server/control_plane.py
@@ -26,7 +26,18 @@ from dify_agent.agent_stub.protocol.agent_stub import (
from dify_agent.agent_stub.server.agent_stub_config import AgentStubConfigRequestError, AgentStubConfigRequestHandler
from dify_agent.agent_stub.server.agent_stub_drive import AgentStubDriveRequestError, AgentStubDriveRequestHandler
from dify_agent.agent_stub.server.agent_stub_files import AgentStubFileRequestError, AgentStubFileRequestHandler
-from dify_agent.agent_stub.server.tokens.agent_stub import AgentStubPrincipal, AgentStubTokenCodec, AgentStubTokenError
+from dify_agent.agent_stub.server.tokens.agent_stub import (
+ AgentStubPrincipal,
+ AgentStubTokenCodec,
+ AgentStubTokenError,
+ AgentStubTokenExpiredError,
+)
+
+
+_AGENT_STUB_AUTHORIZATION_EXPIRED_DETAIL = {
+ "code": "agent_stub_authorization_expired",
+ "message": "Agent Stub authorization expired after 5 minutes; start a new shell tool call and retry the command.",
+}
class AgentStubControlPlaneError(RuntimeError):
@@ -65,7 +76,7 @@ class AgentStubControlPlaneService:
async def connect(self, *, authorization: str | None) -> AgentStubConnectResponse:
"""Authenticate and handle one connect request."""
- _ = self._authenticate(authorization)
+ _ = self._authenticate(authorization, expose_expiration=True)
return AgentStubConnectResponse(connection_id=self.connection_id_factory(), status="connected")
async def create_file_upload_request(
@@ -73,9 +84,10 @@ class AgentStubControlPlaneService:
*,
request: AgentStubFileUploadRequest,
authorization: str | None,
+ expose_expiration: bool = False,
) -> AgentStubFileUploadResponse:
"""Authenticate and delegate one already-validated file-upload request."""
- principal = self._authenticate(authorization)
+ principal = self._authenticate(authorization, expose_expiration=expose_expiration)
handler = self._require_file_request_handler()
try:
return await handler.create_upload_request(principal=principal, request=request)
@@ -89,7 +101,7 @@ class AgentStubControlPlaneService:
authorization: str | None,
) -> AgentStubFileDownloadResponse:
"""Authenticate and delegate one already-validated file-download request."""
- principal = self._authenticate(authorization)
+ principal = self._authenticate(authorization, expose_expiration=True)
if request.config is not None:
handler = self._require_config_request_handler()
try:
@@ -127,7 +139,7 @@ class AgentStubControlPlaneService:
*,
authorization: str | None,
) -> AgentStubConfigManifestResponse:
- principal = self._authenticate(authorization)
+ principal = self._authenticate(authorization, expose_expiration=True)
handler = self._require_config_request_handler()
try:
return await handler.manifest(principal=principal)
@@ -140,7 +152,7 @@ class AgentStubControlPlaneService:
name: str,
authorization: str | None,
) -> dict[str, object]:
- principal = self._authenticate(authorization)
+ principal = self._authenticate(authorization, expose_expiration=True)
handler = self._require_config_request_handler()
try:
return await handler.inspect_skill(principal=principal, name=name)
@@ -153,7 +165,7 @@ class AgentStubControlPlaneService:
request: AgentStubConfigPushRequest,
authorization: str | None,
) -> AgentStubConfigPushResponse:
- principal = self._authenticate(authorization)
+ principal = self._authenticate(authorization, expose_expiration=True)
handler = self._require_config_request_handler()
try:
return await handler.push(principal=principal, request=request)
@@ -166,7 +178,7 @@ class AgentStubControlPlaneService:
env_text: str,
authorization: str | None,
) -> dict[str, object]:
- principal = self._authenticate(authorization)
+ principal = self._authenticate(authorization, expose_expiration=True)
handler = self._require_config_request_handler()
try:
return await handler.update_env(principal=principal, env_text=env_text)
@@ -179,7 +191,7 @@ class AgentStubControlPlaneService:
note: str,
authorization: str | None,
) -> dict[str, object]:
- principal = self._authenticate(authorization)
+ principal = self._authenticate(authorization, expose_expiration=True)
handler = self._require_config_request_handler()
try:
return await handler.update_note(principal=principal, note=note)
@@ -200,12 +212,19 @@ class AgentStubControlPlaneService:
except AgentStubDriveRequestError as exc:
raise AgentStubControlPlaneError(exc.status_code, exc.detail) from exc
- def _authenticate(self, authorization: str | None) -> AgentStubPrincipal:
+ def _authenticate(self, authorization: str | None, *, expose_expiration: bool = False) -> AgentStubPrincipal:
token_codec = self.token_codec
if token_codec is None:
raise AgentStubConfigurationError(503, "Agent Stub is not configured")
try:
return token_codec.decode_authorization_header(authorization)
+ except AgentStubTokenExpiredError as exc:
+ detail = (
+ _AGENT_STUB_AUTHORIZATION_EXPIRED_DETAIL
+ if expose_expiration
+ else "invalid or missing Agent Stub authorization"
+ )
+ raise AgentStubAuthenticationError(401, detail) from exc
except AgentStubTokenError as exc:
raise AgentStubAuthenticationError(401, "invalid or missing Agent Stub authorization") from exc
diff --git a/dify-agent/src/dify_agent/agent_stub/server/routes/agent_stub.py b/dify-agent/src/dify_agent/agent_stub/server/routes/agent_stub.py
index 22e8fa9f94f..5bcaa978b6a 100644
--- a/dify-agent/src/dify_agent/agent_stub/server/routes/agent_stub.py
+++ b/dify-agent/src/dify_agent/agent_stub/server/routes/agent_stub.py
@@ -62,9 +62,14 @@ def create_agent_stub_http_router(
async def create_file_upload_request(
request: AgentStubFileUploadRequest,
authorization: str | None = Header(default=None, alias="Authorization"),
+ expose_expiration: bool = False,
) -> AgentStubFileUploadResponse:
try:
- return await service.create_file_upload_request(request=request, authorization=authorization)
+ return await service.create_file_upload_request(
+ request=request,
+ authorization=authorization,
+ expose_expiration=expose_expiration,
+ )
except AgentStubControlPlaneError as exc:
raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc
diff --git a/dify-agent/src/dify_agent/agent_stub/server/tokens/__init__.py b/dify-agent/src/dify_agent/agent_stub/server/tokens/__init__.py
index 278b3aaccb9..ca261562e76 100644
--- a/dify-agent/src/dify_agent/agent_stub/server/tokens/__init__.py
+++ b/dify-agent/src/dify_agent/agent_stub/server/tokens/__init__.py
@@ -9,6 +9,7 @@ from dify_agent.agent_stub.server.tokens.agent_stub import (
AgentStubTokenClaims,
AgentStubTokenCodec,
AgentStubTokenError,
+ AgentStubTokenExpiredError,
decode_server_secret_key,
derive_agent_stub_jwe_key,
)
@@ -22,6 +23,7 @@ __all__ = [
"AgentStubTokenClaims",
"AgentStubTokenCodec",
"AgentStubTokenError",
+ "AgentStubTokenExpiredError",
"decode_server_secret_key",
"derive_agent_stub_jwe_key",
]
diff --git a/dify-agent/src/dify_agent/agent_stub/server/tokens/agent_stub.py b/dify-agent/src/dify_agent/agent_stub/server/tokens/agent_stub.py
index 7dc87e8d426..466fbe2581e 100644
--- a/dify-agent/src/dify_agent/agent_stub/server/tokens/agent_stub.py
+++ b/dify-agent/src/dify_agent/agent_stub/server/tokens/agent_stub.py
@@ -30,7 +30,7 @@ from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
AGENT_STUB_TOKEN_ISSUER = "dify-agent-server"
AGENT_STUB_TOKEN_AUDIENCE = "dify-agent-agent-stub"
AGENT_STUB_TOKEN_SCOPE_CONNECT = "agent_stub:connect"
-AGENT_STUB_TOKEN_TTL_SECONDS = 24 * 60 * 60
+AGENT_STUB_TOKEN_TTL_SECONDS = 5 * 60
_AGENT_STUB_JWE_PURPOSE = b"dify-agent:agent-stub:jwe:v1"
_REQUIRED_SERVER_SECRET_BYTES = 32
_BASE64URL_TEXT_PATTERN = re.compile(r"^[A-Za-z0-9_-]+$")
@@ -41,6 +41,10 @@ class AgentStubTokenError(RuntimeError):
"""Raised when an Agent Stub bearer token is missing or invalid."""
+class AgentStubTokenExpiredError(AgentStubTokenError):
+ """Raised when an otherwise valid Agent Stub bearer token has expired."""
+
+
class AgentStubShellClaims(BaseModel):
"""Optional shell-session claims embedded in Agent Stub tokens."""
@@ -100,7 +104,7 @@ class AgentStubTokenCodec:
session_id: str | None = None,
now: int | None = None,
) -> AgentStubTokenClaims:
- """Build the fixed-24h claim set for one Agent Stub connection token."""
+ """Build the fixed-five-minute claim set for one Agent Stub connection token."""
issued_at = _timestamp(now)
shell_claims = AgentStubShellClaims(session_id=session_id) if session_id is not None else None
return AgentStubTokenClaims(
@@ -122,7 +126,7 @@ class AgentStubTokenCodec:
session_id: str | None = None,
now: int | None = None,
) -> str:
- """Encode one fixed-24h Agent Stub compact JWE bearer token."""
+ """Encode one fixed-five-minute Agent Stub compact JWE bearer token."""
return self.encode_claims(self.build_connection_claims(execution_context, session_id=session_id, now=now))
def encode_claims(self, claims: AgentStubTokenClaims) -> str:
@@ -198,12 +202,16 @@ def _validate_claims(claims: AgentStubTokenClaims, *, now: int) -> None:
raise AgentStubTokenError(f"Agent Stub bearer token issuer must be {AGENT_STUB_TOKEN_ISSUER!r}")
if claims.aud != AGENT_STUB_TOKEN_AUDIENCE:
raise AgentStubTokenError(f"Agent Stub bearer token audience must be {AGENT_STUB_TOKEN_AUDIENCE!r}")
+ if claims.exp <= claims.iat:
+ raise AgentStubTokenError("Agent Stub bearer token expiration must be after its issue time")
+ if claims.exp - claims.iat > AGENT_STUB_TOKEN_TTL_SECONDS:
+ raise AgentStubTokenError("Agent Stub bearer token lifetime exceeds the maximum allowed lifetime")
+ if AGENT_STUB_TOKEN_SCOPE_CONNECT not in claims.scope:
+ raise AgentStubTokenError(f"Agent Stub bearer token scope must include {AGENT_STUB_TOKEN_SCOPE_CONNECT!r}")
if now < claims.nbf:
raise AgentStubTokenError("Agent Stub bearer token is not valid yet")
if now >= claims.exp:
- raise AgentStubTokenError("Agent Stub bearer token is expired")
- if AGENT_STUB_TOKEN_SCOPE_CONNECT not in claims.scope:
- raise AgentStubTokenError(f"Agent Stub bearer token scope must include {AGENT_STUB_TOKEN_SCOPE_CONNECT!r}")
+ raise AgentStubTokenExpiredError("Agent Stub bearer token is expired")
def _hkdf_sha256(input_key_material: bytes, *, info: bytes, length: int) -> bytes:
@@ -249,6 +257,7 @@ __all__ = [
"AgentStubTokenClaims",
"AgentStubTokenCodec",
"AgentStubTokenError",
+ "AgentStubTokenExpiredError",
"decode_server_secret_key",
"derive_agent_stub_jwe_key",
]
diff --git a/dify-agent/src/dify_agent/layers/_agent_cli_help.json b/dify-agent/src/dify_agent/layers/_agent_cli_help.json
index 66578c3d9e0..c8942b2ae11 100644
--- a/dify-agent/src/dify_agent/layers/_agent_cli_help.json
+++ b/dify-agent/src/dify_agent/layers/_agent_cli_help.json
@@ -19,7 +19,8 @@
"drive list": "List drive files visible to the current sandbox execution.\n\nUsage:\n dify-agent drive list [REMOTE_PREFIX] [flags]\n\nFlags:\n -h, --help help for list\n --json Emit the drive manifest as JSON.",
"drive pull": "Pull one or more drive keys/prefixes into one local directory tree.\n\nUsage:\n dify-agent drive pull [REMOTE]... [flags]\n\nFlags:\n -h, --help help for pull\n --json Emit the pull result as JSON.\n --to string Local base directory for pulled drive files.",
"drive push": "Upload one local file or directory into the agent drive.\n\nUsage:\n dify-agent drive push LOCAL_PATH REMOTE_PATH [flags]\n\nFlags:\n -h, --help help for push\n --json Accepted for consistency; drive push output is already emitted as JSON.\n --kind string Directory upload kind: skill or dir.",
- "file": "Upload or download workflow files through the Agent Stub.\n\nUsage:\n dify-agent file [command]\n\nAvailable Commands:\n download Download one workflow file mapping into the local sandbox directory.\n upload Upload one sandbox-local file as a ToolFile output reference.\n\nFlags:\n -h, --help help for file\n\nUse \"dify-agent file [command] --help\" for more information about a command.",
+ "file": "Upload or download workflow files through the Agent Stub.\n\nUsage:\n dify-agent file [command]\n\nAvailable Commands:\n download Download one workflow file mapping into the local sandbox directory.\n public-url Create a browser-visible download URL for an existing ToolFile reference.\n upload Upload one sandbox-local file as a ToolFile output reference.\n\nFlags:\n -h, --help help for file\n\nUse \"dify-agent file [command] --help\" for more information about a command.",
"file download": "Download one workflow file mapping into the local sandbox directory.\n\nUsage:\n dify-agent file download TRANSFER_METHOD REFERENCE_OR_URL [flags]\n\nFlags:\n -h, --help help for download\n --to string Local directory for the downloaded file.",
+ "file public-url": "Create a browser-visible download URL for an existing ToolFile reference.\n\nUsage:\n dify-agent file public-url REFERENCE [flags]\n\nFlags:\n -h, --help help for public-url",
"file upload": "Upload one sandbox-local file as a ToolFile output reference.\n\nUsage:\n dify-agent file upload PATH [flags]\n\nFlags:\n -h, --help help for upload\n --no-download-link Skip creating a public download link after upload."
}
diff --git a/dify-agent/src/dify_agent/layers/config/layer.py b/dify-agent/src/dify_agent/layers/config/layer.py
index 7d68202d2a0..730cdc6b15c 100644
--- a/dify-agent/src/dify_agent/layers/config/layer.py
+++ b/dify-agent/src/dify_agent/layers/config/layer.py
@@ -49,6 +49,7 @@ _CONFIG_CLI_MUTATION_HELP_COMMANDS: dict[str, tuple[str, ...]] = {
}
_AGENT_FILE_CLI_HELP_COMMANDS: dict[str, tuple[str, ...]] = {
"dify-agent file upload --help": ("file", "upload"),
+ "dify-agent file public-url --help": ("file", "public-url"),
"dify-agent file download --help": ("file", "download"),
}
_CONFIG_CONTEXT_EXCLUDE = {"mentioned_skill_names": True, "mentioned_file_names": True}
diff --git a/dify-agent/src/dify_agent/layers/shell/layer.py b/dify-agent/src/dify_agent/layers/shell/layer.py
index 87f033c68d3..e4f4987e19c 100644
--- a/dify-agent/src/dify_agent/layers/shell/layer.py
+++ b/dify-agent/src/dify_agent/layers/shell/layer.py
@@ -219,6 +219,7 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
shell_redact_patterns: list[str] = field(default_factory=list)
agent_stub_api_base_url: str | None = None
agent_stub_token_factory: ShellAgentStubTokenFactory | None = None
+ _job_agent_stub_tokens: dict[str, str] = field(default_factory=dict, init=False, repr=False)
@classmethod
@override
@@ -300,10 +301,12 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
async def _tool_run(self, script: str, timeout: float = DEFAULT_TIMEOUT_SECONDS) -> ShellRunToolResult:
try:
+ env = self._build_shell_command_env(include_agent_stub_env=True)
+ agent_stub_token = env.get(AGENT_STUB_AUTH_JWE_ENV_VAR)
result = await self._require_resource().commands.run(
_wrap_user_script(script, self.config),
cwd=self._require_workspace_cwd(),
- env=self._build_shell_command_env(include_agent_stub_env=True),
+ env=env,
timeout=timeout,
)
observation = await render_prompt_observation_from_result(
@@ -313,6 +316,10 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
)
self._remember_job_id(result.job_id)
self._remember_job_offset(result.job_id, observation.offset)
+ if agent_stub_token is not None and not result.done:
+ self._job_agent_stub_tokens[result.job_id] = agent_stub_token
+ else:
+ self._job_agent_stub_tokens.pop(result.job_id, None)
return _tagged_shell_observation(
_metadata_dict(
job_id=result.job_id,
@@ -321,7 +328,7 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
exit_code=result.exit_code,
output_path=observation.output_path,
),
- self._redact_output(observation.text),
+ self._redact_output(observation.text, sensitive_values=(agent_stub_token,)),
)
except (RuntimeError, ValueError) as exc:
return _tool_error_from_exception(exc)
@@ -339,6 +346,12 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
)
self._remember_job_id(result.job_id)
self._remember_job_offset(result.job_id, observation.offset)
+ redacted_output = self._redact_output(
+ observation.text,
+ sensitive_values=(self._job_agent_stub_tokens.get(job_id),),
+ )
+ if result.done:
+ self._job_agent_stub_tokens.pop(job_id, None)
return _tagged_shell_observation(
_metadata_dict(
job_id=result.job_id,
@@ -347,7 +360,7 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
exit_code=result.exit_code,
output_path=observation.output_path,
),
- self._redact_output(observation.text),
+ redacted_output,
)
except (RuntimeError, ValueError) as exc:
return _tool_error_from_exception(exc, job_id=job_id)
@@ -365,6 +378,12 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
)
self._remember_job_id(result.job_id)
self._remember_job_offset(result.job_id, observation.offset)
+ redacted_output = self._redact_output(
+ observation.text,
+ sensitive_values=(self._job_agent_stub_tokens.get(job_id),),
+ )
+ if result.done:
+ self._job_agent_stub_tokens.pop(job_id, None)
return _tagged_shell_observation(
_metadata_dict(
job_id=result.job_id,
@@ -373,7 +392,7 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
exit_code=result.exit_code,
output_path=observation.output_path,
),
- self._redact_output(observation.text),
+ redacted_output,
)
except (RuntimeError, ValueError) as exc:
return _tool_error_from_exception(exc, job_id=job_id)
@@ -390,6 +409,7 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
result = await self._require_resource().commands.interrupt(job_id, grace_seconds=grace_seconds)
self._remember_job_id(result.job_id)
self._remember_job_offset(result.job_id, result.offset)
+ self._job_agent_stub_tokens.pop(result.job_id, None)
output_path: str | None = None
try:
# Once the interrupt itself succeeds, resolving the output path is
@@ -509,6 +529,7 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
def _clear_tracked_jobs(self) -> None:
self.runtime_state.job_offsets = {}
self.runtime_state.job_ids = []
+ self._job_agent_stub_tokens.clear()
def _build_shell_command_env(
self,
@@ -536,7 +557,7 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
env.update(agent_stub_env)
return env
- def _redact_output(self, text: str) -> str:
+ def _redact_output(self, text: str, *, sensitive_values: Sequence[str | None] = ()) -> str:
"""Redact sensitive content from shell output before the model sees it.
Two layers of redaction are applied:
@@ -550,11 +571,11 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
"""
if not text:
return text
- # Built-in: always redact the JWE token value.
- env = self._build_shell_command_env(include_agent_stub_env=True)
- jwe_value = env.get(AGENT_STUB_AUTH_JWE_ENV_VAR)
- if jwe_value and len(jwe_value) > 8:
- text = text.replace(jwe_value, "***")
+ # Built-in: always redact actual sensitive values supplied by the
+ # command owner. Redaction must never mint replacement credentials.
+ for value in sensitive_values:
+ if value and len(value) > 8:
+ text = text.replace(value, "***")
# Server-level + per-agent regex patterns.
for pattern in (*self.shell_redact_patterns, *self.config.redact_patterns):
text = re.sub(pattern, "***", text)
diff --git a/dify-agent/tests/local/dify_agent/agent_stub/server/test_agent_stub_routes.py b/dify-agent/tests/local/dify_agent/agent_stub/server/test_agent_stub_routes.py
index 155835f5d25..ef6a4bf6849 100644
--- a/dify-agent/tests/local/dify_agent/agent_stub/server/test_agent_stub_routes.py
+++ b/dify-agent/tests/local/dify_agent/agent_stub/server/test_agent_stub_routes.py
@@ -18,7 +18,7 @@ from dify_agent.agent_stub.protocol.agent_stub import (
from dify_agent.agent_stub.server.agent_stub_drive import AgentStubDriveRequestError, AgentStubDriveRequestHandler
from dify_agent.agent_stub.server.agent_stub_files import AgentStubFileRequestError, AgentStubFileRequestHandler
from dify_agent.agent_stub.server.routes.agent_stub import create_agent_stub_http_router
-from dify_agent.agent_stub.server.tokens.agent_stub import AgentStubTokenCodec
+from dify_agent.agent_stub.server.tokens.agent_stub import AGENT_STUB_TOKEN_TTL_SECONDS, AgentStubTokenCodec
from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
@@ -91,6 +91,81 @@ def test_agent_stub_connections_route_returns_401_for_invalid_bearer_token() ->
assert response.json()["detail"] == "invalid or missing Agent Stub authorization"
+def test_agent_stub_connections_route_returns_structured_401_for_expired_bearer_token() -> None:
+ codec = _token_codec()
+ token = codec.encode_connection_token(
+ _execution_context(),
+ now=int(time.time()) - AGENT_STUB_TOKEN_TTL_SECONDS - 1,
+ )
+ app = FastAPI()
+ app.include_router(create_agent_stub_http_router(codec))
+ client = TestClient(app)
+
+ response = client.post(
+ "/agent-stub/connections",
+ headers={"Authorization": f"Bearer {token}"},
+ json={"protocol_version": 1, "argv": []},
+ )
+
+ assert response.status_code == 401
+ assert response.json()["detail"] == {
+ "code": "agent_stub_authorization_expired",
+ "message": "Agent Stub authorization expired after 5 minutes; start a new shell tool call and retry the command.",
+ }
+
+
+def test_agent_stub_file_upload_route_exposes_expiration_when_requested() -> None:
+ codec = _token_codec()
+ token = codec.encode_connection_token(
+ _execution_context(),
+ now=int(time.time()) - AGENT_STUB_TOKEN_TTL_SECONDS - 1,
+ )
+ app = FastAPI()
+ app.include_router(create_agent_stub_http_router(codec))
+ client = TestClient(app)
+ headers = {"Authorization": f"Bearer {token}"}
+ payload = {"filename": "report.pdf", "mimetype": "application/pdf"}
+
+ opted_in_response = client.post(
+ "/agent-stub/files/upload-request",
+ headers=headers,
+ params={"expose_expiration": "true"},
+ json=payload,
+ )
+
+ assert opted_in_response.status_code == 401
+ assert opted_in_response.json()["detail"]["code"] == "agent_stub_authorization_expired"
+
+
+def test_agent_stub_file_download_and_config_routes_return_structured_401_for_expired_token() -> None:
+ codec = _token_codec()
+ token = codec.encode_connection_token(
+ _execution_context(),
+ now=int(time.time()) - AGENT_STUB_TOKEN_TTL_SECONDS - 1,
+ )
+ app = FastAPI()
+ app.include_router(create_agent_stub_http_router(codec))
+ client = TestClient(app)
+ headers = {"Authorization": f"Bearer {token}"}
+ expected_detail = {
+ "code": "agent_stub_authorization_expired",
+ "message": "Agent Stub authorization expired after 5 minutes; start a new shell tool call and retry the command.",
+ }
+
+ responses = [
+ client.post(
+ "/agent-stub/files/download-request",
+ headers=headers,
+ json={"file": {"transfer_method": "tool_file", "reference": _reference("tool-file-1")}},
+ ),
+ client.get("/agent-stub/config/manifest", headers=headers),
+ ]
+
+ for response in responses:
+ assert response.status_code == 401
+ assert response.json()["detail"] == expected_detail
+
+
def test_agent_stub_connections_route_returns_503_when_server_has_no_token_codec() -> None:
app = FastAPI()
app.include_router(create_agent_stub_http_router(None))
diff --git a/dify-agent/tests/local/dify_agent/agent_stub/server/tokens/test_agent_stub.py b/dify-agent/tests/local/dify_agent/agent_stub/server/tokens/test_agent_stub.py
index 75823ef501f..ba1f5d6d452 100644
--- a/dify-agent/tests/local/dify_agent/agent_stub/server/tokens/test_agent_stub.py
+++ b/dify-agent/tests/local/dify_agent/agent_stub/server/tokens/test_agent_stub.py
@@ -12,6 +12,7 @@ from dify_agent.agent_stub.server.tokens.agent_stub import (
AGENT_STUB_TOKEN_TTL_SECONDS,
AgentStubTokenCodec,
AgentStubTokenError,
+ AgentStubTokenExpiredError,
decode_server_secret_key,
)
from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
@@ -54,13 +55,26 @@ def test_agent_stub_token_codec_rejects_expired_tokens() -> None:
codec = _codec()
token = codec.encode_connection_token(_execution_context(), now=1_780_395_720)
- with pytest.raises(AgentStubTokenError, match="expired"):
+ with pytest.raises(AgentStubTokenExpiredError, match="expired"):
_ = codec.decode_authorization_header(
f"Bearer {token}",
- now=1_780_395_720 + AGENT_STUB_TOKEN_TTL_SECONDS + 1,
+ now=1_780_395_720 + AGENT_STUB_TOKEN_TTL_SECONDS,
)
[email protected]("expiration_offset", [0, AGENT_STUB_TOKEN_TTL_SECONDS + 1])
+def test_agent_stub_token_codec_rejects_invalid_declared_lifetime(expiration_offset: int) -> None:
+ codec = _codec()
+ issued_at = 1_780_395_720
+ claims = codec.build_connection_claims(_execution_context(), now=issued_at)
+ token = codec.encode_claims(claims.model_copy(update={"exp": issued_at + expiration_offset}))
+
+ with pytest.raises(AgentStubTokenError) as exc_info:
+ _ = codec.decode_authorization_header(f"Bearer {token}", now=issued_at)
+
+ assert not isinstance(exc_info.value, AgentStubTokenExpiredError)
+
+
def test_agent_stub_token_codec_rejects_tokens_before_nbf() -> None:
codec = _codec()
claims = codec.build_connection_claims(_execution_context(), now=1_780_395_720)
@@ -86,6 +100,13 @@ def test_agent_stub_token_codec_rejects_wrong_audience_and_scope() -> None:
with pytest.raises(AgentStubTokenError, match=AGENT_STUB_TOKEN_SCOPE_CONNECT):
_ = codec.decode_authorization_header(f"Bearer {wrong_scope_token}", now=1_780_395_720)
+ with pytest.raises(AgentStubTokenError, match=AGENT_STUB_TOKEN_SCOPE_CONNECT) as exc_info:
+ _ = codec.decode_authorization_header(
+ f"Bearer {wrong_scope_token}",
+ now=1_780_395_720 + AGENT_STUB_TOKEN_TTL_SECONDS,
+ )
+ assert not isinstance(exc_info.value, AgentStubTokenExpiredError)
+
def test_agent_stub_token_codec_rejects_wrong_key_and_malformed_authorization_header() -> None:
codec = _codec()
@@ -107,6 +128,7 @@ def test_agent_stub_token_codec_builds_fixed_server_claims() -> None:
assert claims.iss == AGENT_STUB_TOKEN_ISSUER
assert claims.aud == AGENT_STUB_TOKEN_AUDIENCE
assert claims.scope == [AGENT_STUB_TOKEN_SCOPE_CONNECT]
+ assert AGENT_STUB_TOKEN_TTL_SECONDS == 300
assert claims.exp - claims.iat == AGENT_STUB_TOKEN_TTL_SECONDS
assert claims.shell is not None
assert claims.shell.session_id == "abc12ff"
diff --git a/dify-agent/tests/local/dify_agent/layers/config/test_layer.py b/dify-agent/tests/local/dify_agent/layers/config/test_layer.py
index 990a19eb477..ce9435a4b46 100644
--- a/dify-agent/tests/local/dify_agent/layers/config/test_layer.py
+++ b/dify-agent/tests/local/dify_agent/layers/config/test_layer.py
@@ -133,6 +133,7 @@ async def test_on_context_create_computes_runtime_fields_and_pulls_mentioned_ass
assert layer.runtime_state.pulled_file_outputs == {"guide.txt": "/workspace/.dify_conf/files/guide.txt"}
assert "dify-agent config note push --help" in layer.runtime_state.config_cli_help
assert "dify-agent file upload --help" in layer.runtime_state.config_cli_help
+ assert "dify-agent file public-url --help" in layer.runtime_state.config_cli_help
assert "dify-agent file download --help" in layer.runtime_state.config_cli_help
assert layer.runtime_state.push_spec_json_schema == ""
suffix_prompt = layer.build_suffix_prompt()
@@ -140,8 +141,12 @@ async def test_on_context_create_computes_runtime_fields_and_pulls_mentioned_ass
"Agent file CLI reference for installed `dify-agent`:"
)
assert "$ dify-agent file upload --help" in suffix_prompt
+ assert "$ dify-agent file public-url --help" in suffix_prompt
assert "$ dify-agent file download --help" in suffix_prompt
assert suffix_prompt.index("$ dify-agent file upload --help") < suffix_prompt.index(
+ "$ dify-agent file public-url --help"
+ )
+ assert suffix_prompt.index("$ dify-agent file public-url --help") < suffix_prompt.index(
"$ dify-agent file download --help"
)
assert _AGENT_FILE_UPLOAD_REPLY_HINT in suffix_prompt
diff --git a/dify-agent/tests/local/dify_agent/layers/shell/test_layer.py b/dify-agent/tests/local/dify_agent/layers/shell/test_layer.py
index d8b07395774..b3362d2c033 100644
--- a/dify-agent/tests/local/dify_agent/layers/shell/test_layer.py
+++ b/dify-agent/tests/local/dify_agent/layers/shell/test_layer.py
@@ -354,6 +354,7 @@ def test_shell_layer_suspend_cleans_tracked_jobs_without_owning_sandbox() -> Non
commands = FakeCommands()
layer, _provider = _layer(commands=commands)
layer.runtime_state = _runtime_state()
+ layer._job_agent_stub_tokens.update({"job-1": "token-1", "job-2": "token-2"})
async def scenario() -> None:
async with layer.resource_context():
@@ -361,6 +362,7 @@ def test_shell_layer_suspend_cleans_tracked_jobs_without_owning_sandbox() -> Non
asyncio.run(scenario())
assert commands.delete_calls == []
+ assert layer._job_agent_stub_tokens == {}
def test_shell_layer_resume_requires_active_sandbox_lease_only() -> None:
@@ -383,6 +385,7 @@ def test_shell_layer_delete_cleans_tracked_jobs_without_deleting_workspace() ->
layer, _provider = _layer(commands=commands)
_bind_execution_context(layer)
layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 9})
+ layer._job_agent_stub_tokens["user-job"] = "long-lived-test-token"
async def scenario() -> None:
async with layer.resource_context():
@@ -393,6 +396,7 @@ def test_shell_layer_delete_cleans_tracked_jobs_without_deleting_workspace() ->
assert [call.job_id for call in commands.delete_calls] == ["user-job"]
assert layer.runtime_state.job_ids == []
assert layer.runtime_state.job_offsets == {}
+ assert layer._job_agent_stub_tokens == {}
def test_shell_layer_tools_map_inputs_and_maintain_offsets_with_tail_end() -> None:
@@ -582,6 +586,7 @@ def test_shell_interrupt_succeeds_when_tail_lookup_fails() -> None:
layer, _provider = _layer(commands=commands)
tools = {tool.name: tool for tool in layer.tools}
layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22})
+ layer._job_agent_stub_tokens["user-job"] = "actual-long-jwe-token"
async def scenario() -> None:
async with layer.resource_context():
@@ -596,6 +601,7 @@ def test_shell_interrupt_succeeds_when_tail_lookup_fails() -> None:
assert output == "Job was interrupted."
asyncio.run(scenario())
+ assert layer._job_agent_stub_tokens == {}
def test_shell_run_returns_provider_timeout_error_observation_without_unexpected_logging(
@@ -1193,11 +1199,20 @@ def _layer_with_redaction(
return layer, provider
-def test_redact_output_replaces_jwe_token_value() -> None:
- """The JWE token value should always be redacted from shell output."""
- token = "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0.super-secret-token-12345"
+def test_shell_run_issues_one_jwe_and_redaction_does_not_issue_another() -> None:
+ """The output filter must use the exact JWE injected into the shell job."""
+ issued_tokens: list[str] = []
+
+ def token_factory(execution_context: DifyExecutionContextLayerConfig, session_id: str | None) -> str:
+ del execution_context, session_id
+ token = f"actual-long-jwe-token-{len(issued_tokens) + 1}"
+ issued_tokens.append(token)
+ return token
def run_handler(script: str, cwd: str | None, env: Mapping[str, str] | None, timeout: float) -> ShellCommandResult:
+ del script, cwd, timeout
+ assert env is not None
+ token = env["DIFY_AGENT_STUB_AUTH_JWE"]
return _command_result(
"job-1",
status="exited",
@@ -1207,21 +1222,91 @@ def test_redact_output_replaces_jwe_token_value() -> None:
offset=100,
)
+ commands = FakeCommands(run_handler=run_handler)
+ layer, _provider = _layer_with_redaction(commands=commands)
+ layer.agent_stub_token_factory = token_factory
+ _bind_execution_context(layer)
+ layer.runtime_state = _runtime_state()
+ tools = {tool.name: tool for tool in layer.tools}
+
+ async def scenario() -> None:
+ async with layer.resource_context():
+ result = await tools["shell_run"].function_schema.call({"script": "env"}, None) # pyright: ignore[reportArgumentType]
+ _, output = _parse_tagged_observation(result)
+ assert issued_tokens[0] not in output
+ assert "DIFY_AGENT_STUB_AUTH_JWE=***" in output
+
+ asyncio.run(scenario())
+ assert issued_tokens == ["actual-long-jwe-token-1"]
+ assert layer._job_agent_stub_tokens == {}
+
+
+def test_two_running_jobs_redact_and_clean_up_their_own_jwes_independently() -> None:
+ tokens = ["actual-long-jwe-token-for-job-1", "actual-long-jwe-token-for-job-2"]
+ issued_tokens: list[str] = []
+
+ def token_factory(execution_context: DifyExecutionContextLayerConfig, session_id: str | None) -> str:
+ del execution_context, session_id
+ token = tokens[len(issued_tokens)]
+ issued_tokens.append(token)
+ return token
+
+ def run_handler(
+ script: str,
+ cwd: str | None,
+ env: Mapping[str, str] | None,
+ timeout: float,
+ ) -> ShellCommandResult:
+ del script, cwd, timeout
+ assert env is not None
+ token = env["DIFY_AGENT_STUB_AUTH_JWE"]
+ job_id = "job-1" if token == tokens[0] else "job-2"
+ return _command_result(job_id, status="running", done=False, output="started\n", offset=8)
+
commands = FakeCommands(
run_handler=run_handler,
- tail_handler=lambda _: _command_result("job-1", done=True, exit_code=0, status="exited", offset=100),
+ wait_handler=lambda job_id, offset, timeout: _command_result(
+ job_id,
+ status="exited",
+ done=True,
+ exit_code=0,
+ output=f"wait={tokens[0]}\n",
+ offset=20,
+ ),
+ input_handler=lambda job_id, text, offset, timeout: _command_result(
+ job_id,
+ status="exited",
+ done=True,
+ exit_code=0,
+ output=f"input={tokens[1]}\n",
+ offset=40,
+ ),
)
- layer, _provider = _layer_with_redaction(commands=commands, token_value=token)
+ layer, _provider = _layer_with_redaction(commands=commands)
+ layer.agent_stub_token_factory = token_factory
_bind_execution_context(layer)
layer.runtime_state = _runtime_state()
tools = {tool.name: tool for tool in layer.tools}
async def scenario() -> None:
async with layer.resource_context():
- result = await tools["shell_run"].function_schema.call({"script": "env"}, None) # pyright: ignore[reportArgumentType]
- _, output = _parse_tagged_observation(result)
- assert token not in output
- assert "***" in output
+ await tools["shell_run"].function_schema.call({"script": "start first"}, None) # pyright: ignore[reportArgumentType]
+ await tools["shell_run"].function_schema.call({"script": "start second"}, None) # pyright: ignore[reportArgumentType]
+ assert issued_tokens == tokens
+ assert layer._job_agent_stub_tokens == {"job-1": tokens[0], "job-2": tokens[1]}
+
+ wait_result = await tools["shell_wait"].function_schema.call({"job_id": "job-1"}, None) # pyright: ignore[reportArgumentType]
+ _, wait_output = _parse_tagged_observation(wait_result)
+ assert wait_output == "wait=***\n"
+ assert layer._job_agent_stub_tokens == {"job-2": tokens[1]}
+
+ input_result = await tools["shell_input"].function_schema.call(
+ {"job_id": "job-2", "text": "finish\n"},
+ None, # pyright: ignore[reportArgumentType]
+ )
+ _, input_output = _parse_tagged_observation(input_result)
+ assert input_output == "input=***\n"
+ assert layer._job_agent_stub_tokens == {}
asyncio.run(scenario())