fix(run): allow caller-supplied taskUUID instead of always generating (#66)

The API supports caller-provided task identifiers but the CLI rejected taskUUID as a reserved field. Demote taskUUID from Protected to auto-only so it is still excluded from completions and validation but no longer blocked as a key=value argument. If the caller supplies an invalid UUID, Run returns an error before submitting.

Closes RUN-10706

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: danmrichards

internal/api/client.go

@@ -132,8 +132,9 @@ func (c *Client) submit(ctx context.Context, payload map[string]any) ([]json.Raw
 // args is a slice of key=value strings (e.g. ["positivePrompt=hello", "width=1024"]).
 // They are parsed against the model's fetched JSON Schema so that type coercion
 // (string vs number vs bool) is schema-driven rather than best-effort.
-// System fields (taskType, taskUUID, deliveryMethod) are injected automatically;
-// callers must not include them in rawArgs.
+// System fields (taskType) are injected automatically; callers must not include it in args.
+// deliveryMethod may be set via --delivery-method or a key=value argument.
+// taskUUID is optional: supply it to use a specific identifier, or omit it to have one generated.
 //
 // For async delivery Run polls until a success result is received or the context
 // is cancelled. For sync delivery the submit response is returned directly.
@@ -184,7 +185,7 @@ func (c *Client) Run(ctx context.Context, model string, args []string, opts RunO
 	}
 
 	// Parse args against the real schema so type coercion is schema-driven.
-	// Protected fields (taskType, taskUUID, model, deliveryMethod) are rejected here.
+	// Protected fields are rejected here.
 	payload := make(map[string]any, len(args)+4)
 	payload[fieldModel] = model
 	for _, a := range args {
@@ -222,8 +223,21 @@ func (c *Client) Run(ctx context.Context, model string, args []string, opts RunO
 		payload[fieldDeliveryMethod] = deliveryMethod
 	}
 
-	// Inject system fields.
-	taskUUID := uuid.New()
+	// Inject system fields. Use a caller-supplied taskUUID if provided, otherwise generate.
+	var taskUUID uuid.UUID
+	if raw, ok := payload[fieldTaskUUID]; ok {
+		s, ok := raw.(string)
+		if !ok {
+			return nil, fmt.Errorf("taskUUID: expected string UUID, got %T", raw)
+		}
+		parsed, err := uuid.Parse(s)
+		if err != nil {
+			return nil, fmt.Errorf("taskUUID: invalid UUID %q: %w", s, err)
+		}
+		taskUUID = parsed
+	} else {
+		taskUUID = uuid.New()
+	}
 	payload[fieldTaskType] = taskType
 	payload[fieldTaskUUID] = taskUUID
 

internal/api/run_test.go

@@ -401,3 +401,70 @@ func TestClientRun_RawArgs_InvalidKV(t *testing.T) {
 		t.Errorf("expected 0 transport calls, got %d", mock.callCount)
 	}
 }
+
+// TestClientRun_UserProvidedTaskUUID: a caller-supplied taskUUID must be accepted and used
+// (after UUID validation) instead of being overwritten with a new UUID.
+func TestClientRun_UserProvidedTaskUUID(t *testing.T) {
+	const wantUUID = "d58cbacc-bed6-413e-9e4a-b118e4d84035"
+
+	srv := inferenceSchemaServer(t, requestSchemaWithTaskType("imageInference", "sync"))
+
+	mock := &mockTransport{
+		responses: []mockResponse{
+			{data: []json.RawMessage{successItem(t, nil)}},
+		},
+	}
+
+	c := NewClient(mock, slog.Default())
+	c.schemaBaseURLOverride = srv.URL + "/"
+
+	_, err := c.Run(context.Background(), testModelAIR, []string{"taskUUID=" + wantUUID}, RunOptions{})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if len(mock.captured) == 0 {
+		t.Fatal("no transport calls captured")
+	}
+	tasks := mock.captured[0]
+	if len(tasks) == 0 {
+		t.Fatal("submitted tasks slice is empty")
+	}
+	taskBytes, err := json.Marshal(tasks[0])
+	if err != nil {
+		t.Fatalf("marshal captured task: %v", err)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(taskBytes, &payload); err != nil {
+		t.Fatalf("unmarshal captured task: %v", err)
+	}
+	got, ok := payload["taskUUID"]
+	if !ok {
+		t.Fatal("taskUUID not present in submitted payload")
+	}
+	if s, _ := got.(string); s != wantUUID {
+		t.Errorf("taskUUID: got %q, want %q", s, wantUUID)
+	}
+}
+
+// TestClientRun_UserProvidedTaskUUID_Invalid: an invalid UUID value must return
+// an error before any transport call is made.
+func TestClientRun_UserProvidedTaskUUID_Invalid(t *testing.T) {
+	srv := inferenceSchemaServer(t, requestSchemaWithTaskType("imageInference", "sync"))
+
+	mock := &mockTransport{}
+
+	c := NewClient(mock, slog.Default())
+	c.schemaBaseURLOverride = srv.URL + "/"
+
+	_, err := c.Run(context.Background(), testModelAIR, []string{"taskUUID=not-a-uuid"}, RunOptions{})
+	if err == nil {
+		t.Fatal("expected error for invalid taskUUID, got nil")
+	}
+	if !strings.Contains(err.Error(), "taskUUID") {
+		t.Errorf("expected error to mention %q, got: %v", "taskUUID", err)
+	}
+	if mock.callCount != 0 {
+		t.Errorf("expected 0 transport calls, got %d", mock.callCount)
+	}
+}

internal/schema/schema.go

@@ -106,8 +106,7 @@ var ManagedFields = map[string]ManagedField{
 		Hint:      "use the --task-type flag instead",
 	},
 	"taskUUID": {
-		Protected: true,
-		Hint:      "this field is system-generated and cannot be set manually",
+		Protected: false,
 	},
 	"deliveryMethod": {
 		Protected: false,

internal/schema/schema_test.go

@@ -629,10 +629,10 @@ func TestIsProtected_ModelRejected(t *testing.T) {
 	}
 }
 
-func TestIsProtected_TaskUUIDRejected(t *testing.T) {
+func TestIsProtected_TaskUUIDAllowed(t *testing.T) {
 	_, blocked := schema.IsProtected("taskUUID")
-	if !blocked {
-		t.Error("expected taskUUID to be protected")
+	if blocked {
+		t.Error("taskUUID must not be protected — callers may supply their own task identifier")
 	}
 }